From: Boštjan Mejak Date: Tue, 31 May 2022 18:25:57 +0000 (+0200) Subject: Wording of help output and comments. X-Git-Url: https://git.sesse.net/?p=stockfish;a=commitdiff_plain;h=809849fa275512225d19e280809f227990d97eb1 Wording of help output and comments. Improved the output text that is diplayed when executing the 'help' command. Also, some comments were fixed along the way. closes https://github.com/official-stockfish/Stockfish/pull/4048 closes https://github.com/official-stockfish/Stockfish/pull/4044 No functional change --- diff --git a/AUTHORS b/AUTHORS index 715f83b1..fc885acb 100644 --- a/AUTHORS +++ b/AUTHORS @@ -35,6 +35,7 @@ Ben Chaney (Chaneybenjamini) Ben Koshy (BKSpurgeon) Bill Henry (VoyagerOne) Bojun Guo (noobpwnftw, Nooby) +BoÅ¡tjan Mejak (PedanticHacker) braich Brian Sheppard (SapphireBrand, briansheppard-toast) Bruno de Melo Costa (BM123499) diff --git a/src/uci.cpp b/src/uci.cpp index c28cf6d1..c0bacfaf 100644 --- a/src/uci.cpp +++ b/src/uci.cpp @@ -40,14 +40,14 @@ extern vector setup_bench(const Position&, istream&); namespace { - // FEN string of the initial position, normal chess + // FEN string for the initial position in standard chess const char* StartFEN = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"; - // position() is called when engine receives the "position" UCI command. - // The function sets up the position described in the given FEN string ("fen") - // or the starting position ("startpos") and then makes the moves given in the - // following move list ("moves"). + // position() is called when the engine receives the "position" UCI command. + // It sets up the position that is described in the given FEN string ("fen") or + // the initial position ("startpos") and then makes the moves given in the following + // move list ("moves"). void position(Position& pos, istringstream& is, StateListPtr& states) { @@ -59,7 +59,7 @@ namespace { if (token == "startpos") { fen = StartFEN; - is >> token; // Consume "moves" token if any + is >> token; // Consume the "moves" token, if any } else if (token == "fen") while (is >> token && token != "moves") @@ -67,10 +67,10 @@ namespace { else return; - states = StateListPtr(new std::deque(1)); // Drop old and create a new one + states = StateListPtr(new std::deque(1)); // Drop the old state and create a new one pos.set(fen, Options["UCI_Chess960"], &states->back(), Threads.main()); - // Parse move list (if any) + // Parse the move list, if any while (is >> token && (m = UCI::to_move(pos, token)) != MOVE_NONE) { states->emplace_back(); @@ -78,8 +78,8 @@ namespace { } } - // trace_eval() prints the evaluation for the current position, consistent with the UCI - // options set so far. + // trace_eval() prints the evaluation of the current position, consistent with + // the UCI options set so far. void trace_eval(Position& pos) { @@ -93,20 +93,20 @@ namespace { } - // setoption() is called when engine receives the "setoption" UCI command. The - // function updates the UCI option ("name") to the given value ("value"). + // setoption() is called when the engine receives the "setoption" UCI command. + // The function updates the UCI option ("name") to the given value ("value"). void setoption(istringstream& is) { string token, name, value; - is >> token; // Consume "name" token + is >> token; // Consume the "name" token - // Read option name (can contain spaces) + // Read the option name (can contain spaces) while (is >> token && token != "value") name += (name.empty() ? "" : " ") + token; - // Read option value (can contain spaces) + // Read the option value (can contain spaces) while (is >> token) value += (value.empty() ? "" : " ") + token; @@ -117,9 +117,9 @@ namespace { } - // go() is called when engine receives the "go" UCI command. The function sets - // the thinking time and other parameters from the input string, then starts - // the search. + // go() is called when the engine receives the "go" UCI command. The function + // sets the thinking time and other parameters from the input string, then starts + // with a search. void go(Position& pos, istringstream& is, StateListPtr& states) { @@ -127,7 +127,7 @@ namespace { string token; bool ponderMode = false; - limits.startTime = now(); // As early as possible! + limits.startTime = now(); // The search starts as early as possible while (is >> token) if (token == "searchmoves") // Needs to be the last command on the line @@ -151,9 +151,9 @@ namespace { } - // bench() is called when engine receives the "bench" command. Firstly - // a list of UCI commands is setup according to bench parameters, then - // it is run one by one printing a summary at the end. + // bench() is called when the engine receives the "bench" command. + // Firstly, a list of UCI commands is set up according to the bench + // parameters, then it is run one by one, printing a summary at the end. void bench(Position& pos, istream& args, StateListPtr& states) { @@ -184,12 +184,12 @@ namespace { } else if (token == "setoption") setoption(is); else if (token == "position") position(pos, is, states); - else if (token == "ucinewgame") { Search::clear(); elapsed = now(); } // Search::clear() may take some while + else if (token == "ucinewgame") { Search::clear(); elapsed = now(); } // Search::clear() may take a while } elapsed = now() - elapsed + 1; // Ensure positivity to avoid a 'divide by zero' - dbg_print(); // Just before exiting + dbg_print(); cerr << "\n===========================" << "\nTotal time (ms) : " << elapsed @@ -197,36 +197,36 @@ namespace { << "\nNodes/second : " << 1000 * nodes / elapsed << endl; } - // The win rate model returns the probability (per mille) of winning given an eval - // and a game-ply. The model fits rather accurately the LTC fishtest statistics. + // The win rate model returns the probability of winning (in per mille units) given an + // eval and a game ply. It fits the LTC fishtest statistics rather accurately. int win_rate_model(Value v, int ply) { - // The model captures only up to 240 plies, so limit input (and rescale) + // The model only captures up to 240 plies, so limit the input and then rescale double m = std::min(240, ply) / 64.0; - // Coefficients of a 3rd order polynomial fit based on fishtest data - // for two parameters needed to transform eval to the argument of a - // logistic function. + // The coefficients of a third-order polynomial fit is based on the fishtest data + // for two parameters that need to transform eval to the argument of a logistic + // function. double as[] = {-1.17202460e-01, 5.94729104e-01, 1.12065546e+01, 1.22606222e+02}; double bs[] = {-1.79066759, 11.30759193, -17.43677612, 36.47147479}; double a = (((as[0] * m + as[1]) * m + as[2]) * m) + as[3]; double b = (((bs[0] * m + bs[1]) * m + bs[2]) * m) + bs[3]; - // Transform eval to centipawns with limited range + // Transform the eval to centipawns with limited range double x = std::clamp(double(100 * v) / PawnValueEg, -2000.0, 2000.0); - // Return win rate in per mille (rounded to nearest) + // Return the win rate in per mille units rounded to the nearest value return int(0.5 + 1000 / (1 + std::exp((a - x) / b))); } } // namespace -/// UCI::loop() waits for a command from stdin, parses it and calls the appropriate -/// function. Also intercepts EOF from stdin to ensure gracefully exiting if the -/// GUI dies unexpectedly. When called with some command line arguments, e.g. to -/// run 'bench', once the command is executed the function returns immediately. -/// In addition to the UCI ones, also some additional debug commands are supported. +/// UCI::loop() waits for a command from the stdin, parses it and then calls the appropriate +/// function. It also intercepts an end-of-file (EOF) indication from the stdin to ensure a +/// graceful exit if the GUI dies unexpectedly. When called with some command-line arguments, +/// like running 'bench', the function returns immediately after the command is executed. +/// In addition to the UCI ones, some additional debug commands are also supported. void UCI::loop(int argc, char* argv[]) { @@ -240,24 +240,24 @@ void UCI::loop(int argc, char* argv[]) { cmd += std::string(argv[i]) + " "; do { - if (argc == 1 && !getline(cin, cmd)) // Block here waiting for input or EOF + if (argc == 1 && !getline(cin, cmd)) // Wait for an input or an end-of-file (EOF) indication cmd = "quit"; istringstream is(cmd); - token.clear(); // Avoid a stale if getline() returns empty or blank line + token.clear(); // Avoid a stale if getline() returns nothing or a blank line is >> skipws >> token; if ( token == "quit" || token == "stop") Threads.stop = true; - // The GUI sends 'ponderhit' to tell us the user has played the expected move. - // So 'ponderhit' will be sent if we were told to ponder on the same move the - // user has played. We should continue searching but switch from pondering to - // normal search. + // The GUI sends 'ponderhit' to tell that the user has played the expected move. + // So, 'ponderhit' is sent if pondering was done on the same move that the user + // has played. The search should continue, but should also switch from pondering + // to the normal search. else if (token == "ponderhit") - Threads.main()->ponder = false; // Switch to normal search + Threads.main()->ponder = false; // Switch to the normal search else if (token == "uci") sync_cout << "id name " << engine_info(true) @@ -270,8 +270,8 @@ void UCI::loop(int argc, char* argv[]) { else if (token == "ucinewgame") Search::clear(); else if (token == "isready") sync_cout << "readyok" << sync_endl; - // Additional custom non-UCI commands, mainly for debugging. - // Do not use these commands during a search! + // Add custom non-UCI commands, mainly for debugging purposes. + // These commands must not be used during a search! else if (token == "flip") pos.flip(); else if (token == "bench") bench(pos, is, states); else if (token == "d") sync_cout << pos << sync_endl; @@ -286,24 +286,24 @@ void UCI::loop(int argc, char* argv[]) { Eval::NNUE::save_eval(filename); } else if (token == "--help" || token == "help" || token == "--license" || token == "license") - sync_cout << "\nStockfish is a powerful chess engine and free software licensed under the GNU GPLv3." - "\nStockfish is normally used with a separate graphical user interface (GUI)." - "\nStockfish implements the universal chess interface (UCI) to exchange information." - "\nFor further information see https://github.com/official-stockfish/Stockfish#readme" - "\nor the corresponding README.md and Copying.txt files distributed with this program.\n" << sync_endl; + sync_cout << "\nStockfish is a powerful chess engine for playing and analyzing." + "\nIt is released as free software licensed under the GNU GPLv3 License." + "\nStockfish is normally used with a graphical user interface (GUI) and implements" + "\nthe Universal Chess Interface (UCI) protocol to communicate with a GUI, an API, etc." + "\nFor any further information, visit https://github.com/official-stockfish/Stockfish#readme" + "\nor read the corresponding README.md and Copying.txt files distributed along with this program.\n" << sync_endl; else if (!token.empty() && token[0] != '#') sync_cout << "Unknown command: '" << cmd << "'. Type help for more information." << sync_endl; - } while (token != "quit" && argc == 1); // Command line args are one-shot + } while (token != "quit" && argc == 1); // The command-line arguments are one-shot } -/// UCI::value() converts a Value to a string suitable for use with the UCI -/// protocol specification: +/// UCI::value() converts a Value to a string by adhering to the UCI protocol specification: /// /// cp The score from the engine's point of view in centipawns. -/// mate Mate in y moves, not plies. If the engine is getting mated -/// use negative values for y. +/// mate Mate in 'y' moves (not plies). If the engine is getting mated, +/// uses negative values for 'y'. string UCI::value(Value v) { @@ -320,8 +320,8 @@ string UCI::value(Value v) { } -/// UCI::wdl() report WDL statistics given an evaluation and a game ply, based on -/// data gathered for fishtest LTC games. +/// UCI::wdl() reports the win-draw-loss (WDL) statistics given an evaluation +/// and a game ply based on the data gathered for fishtest LTC games. string UCI::wdl(Value v, int ply) { @@ -344,9 +344,9 @@ std::string UCI::square(Square s) { /// UCI::move() converts a Move to a string in coordinate notation (g1f3, a7a8q). -/// The only special case is castling, where we print in the e1g1 notation in -/// normal chess mode, and in e1h1 notation in chess960 mode. Internally all -/// castling moves are always encoded as 'king captures rook'. +/// The only special case is castling where the e1g1 notation is printed in +/// standard chess mode and in e1h1 notation it is printed in Chess960 mode. +/// Internally, all castling moves are always encoded as 'king captures rook'. string UCI::move(Move m, bool chess960) { @@ -376,8 +376,8 @@ string UCI::move(Move m, bool chess960) { Move UCI::to_move(const Position& pos, string& str) { - if (str.length() == 5) // Junior could send promotion piece in uppercase - str[4] = char(tolower(str[4])); + if (str.length() == 5) + str[4] = char(tolower(str[4])); // The promotion piece character must be lowercased for (const auto& m : MoveList(pos)) if (str == UCI::move(m, pos.is_chess960())) diff --git a/src/uci.h b/src/uci.h index 5bb24a4e..76a893f9 100644 --- a/src/uci.h +++ b/src/uci.h @@ -32,15 +32,15 @@ namespace UCI { class Option; -/// Custom comparator because UCI options should be case insensitive +/// Define a custom comparator, because the UCI options should be case-insensitive struct CaseInsensitiveLess { bool operator() (const std::string&, const std::string&) const; }; -/// Our options container is actually a std::map +/// The options container is defined as a std::map typedef std::map OptionsMap; -/// Option class implements an option as defined by UCI protocol +/// The Option class implements each option as specified by the UCI protocol class Option { typedef void (*OnChange)(const Option&);