Doxygen improvements

.gitignore

@@ -48,6 +48,7 @@ build.ninja
 
 # Build directories
 /build*
+/doxygen
 .flatpak-builder
 
 # Nix build artifacts

.readthedocs.yaml

@@ -8,6 +8,15 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
+  apt_packages:
+    - graphviz
+  jobs:
+    pre_build:
+      # Creates the documentation in the doxygen/ subfolder
+      - doxygen
+    post_build:
+      # Move the output to be hosted
+      - mv doxygen/html $READTHEDOCS_OUTPUT/html/Doxygen
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

client/control.cpp

@@ -2518,7 +2518,7 @@ void do_map_click(struct tile *ptile, enum quickselect_type qtype)
 }
 
 /**
-   Quickselecting a unit is normally done with <control> left, right click,
+   Quickselecting a unit is normally done with [control] left, right click,
    for the current tile. Bypassing the stack popup is quite convenient,
    and can be tactically important in furious multiplayer games.
  */

client/shortcuts.cpp

@@ -444,7 +444,7 @@ void shortcut_edit::set_shortcut(const fc_shortcut &shortcut)
 }
 
 /**
- * \reimp
+ * Reimplemented from QObject
  */
 bool shortcut_edit::event(QEvent *event)
 {

client/tileset/drawn_sprite.h

@@ -17,10 +17,10 @@ class QRect;
 struct tileset;
 
 struct drawn_sprite {
-  explicit drawn_sprite(const tileset *ts, const QPixmap *sprite,
+  explicit drawn_sprite(const struct tileset *ts, const QPixmap *sprite,
                         bool foggable = true, int offset_x = 0,
                         int offset_y = 0);
-  explicit drawn_sprite(const tileset *ts, const QPixmap *sprite,
+  explicit drawn_sprite(const struct tileset *ts, const QPixmap *sprite,
                         bool foggable, const QPoint &offset);
   drawn_sprite(const drawn_sprite &other) = default;
   drawn_sprite(drawn_sprite &&other) = default;

client/tileset/layer_base_flags.cpp

@@ -23,7 +23,7 @@ namespace freeciv {
 /**
  * @class layer_base_flags
  *
- * Map layer that draws flags for bases that have @ref EF_SHOW_FLAG set.
+ * Map layer that draws flags for bases that have EF_SHOW_FLAG set.
  */
 
 layer_base_flags::layer_base_flags(struct tileset *ts, const QPoint &offset)

client/utils/colorizer.cpp

@@ -12,7 +12,7 @@
 namespace freeciv {
 
 /**
- * @class colorizer Swaps colors in QPixmap
+ * @class colorizer colorizer.h Swaps colors in QPixmap
  *
  * Starting from a base pixmap, this class generates new pixmaps with one
  * color replaced (for instance, all pink pixels changed to green).

client/views/view_map_common.cpp

@@ -581,7 +581,7 @@ void set_mapview_origin(float gui_x0, float gui_y0)
 
 /**
    Return the scroll dimensions of the clipping window for the mapview
- window..
+   window.
 
    Imagine the entire map in scroll coordinates.  It is a rectangle.  Now
    imagine the mapview "window" sliding around through this rectangle.  How

common/aicore/path_finding.cpp

@@ -92,14 +92,14 @@ struct pf_map {
 /**
  * Casts to `pf_map`
  *
- * \fixme Capitalized because this used to be a macro.
+ * \todo Capitalized because this used to be a macro.
  */
 pf_map *PF_MAP(void *x) { return reinterpret_cast<pf_map *>(x); }
 
 /**
  * Casts to `pf_map`
  *
- * \fixme Capitalized because this used to be a macro.
+ * \todo Capitalized because this used to be a macro.
  */
 const pf_map *PF_MAP(const void *x)
 {

common/game.cpp

@@ -738,10 +738,10 @@ static char *year_suffix()
    Generate a default save file name and place it in the provided buffer.
    Within the name the following custom formats are allowed:
 
-     %R = <reason>
-     %S = <suffix>
-     %T = <game.info.turn>
-     %Y = <game.info.year>
+     %R = [reason]
+     %S = [suffix]
+     %T = [game.info.turn]
+     %Y = [game.info.year]
 
    Examples:
      'freeciv-T%04T-Y%+04Y-%R' => 'freeciv-T0099-Y-0050-manual'

common/mapimg.cpp

@@ -1042,8 +1042,8 @@ bool mapimg_id2str(int id, char *str, size_t str_len)
 
 /**
    Create the requested map image. The filename is created as
-   <basename as used for savegames>-<mapstr>.<mapext> where <mapstr>
-   contains the map definition and <mapext> the selected image extension.
+   `basename as used for savegames-mapstr.mapext` where `mapstr`
+   contains the map definition and `mapext` the selected image extension.
    If 'force' is FALSE, the image is only created if game.info.turn is a
    multiple of the map setting turns.
  */
@@ -1150,9 +1150,8 @@ bool mapimg_create(struct mapdef *pmapdef, bool force, const char *savename,
 
 /**
    Create images which shows all map colors (playercolor, terrain colors).
- One image is created for each supported toolkit and image format. The
- filename will be <basename as used for
- savegames>-colortest-<toolkit>.<format>.
+   One image is created for each supported image format. The filename will be
+   [basename as used for savegames]-colortest.[format].
  */
 bool mapimg_colortest(const char *savename, const char *path)
 {
@@ -1413,11 +1412,10 @@ static void mapimg_log(const char *file, const char *function, int line,
 /**
    Generate an identifier for a map image.
 
-   M<map options>Z<zoom factor>P<players>
+   `M[map options]Z[zoom factor]P[players]`
 
-   <map options>    map options
-   <zoom factor>    zoom factor
-   <players>        player ID or vector of size MAX_NUM_PLAYER_SLOTS [0/1]
+   Where `[players]` is the player ID or vector of size MAX_NUM_PLAYER_SLOTS
+   [0/1].
 
    For the player bitvector all MAX_NUM_PLAYER_SLOTS values are used due to
    the possibility of additional players during the game (civil war,

common/rgbcolor.cpp

@@ -72,8 +72,8 @@ void rgbcolor_destroy(struct rgbcolor *prgbcolor)
 }
 
 /**
-   Lookup an RGB color definition (<colorpath>.red, <colorpath>.green and
-   <colorpath>.blue). Returns TRUE on success and FALSE on error.
+   Lookup an RGB color definition (`[colorpath].red`, `[colorpath].green` and
+   `[colorpath].blue`). Returns TRUE on success and FALSE on error.
  */
 bool rgbcolor_load(struct section_file *file, struct rgbcolor **prgbcolor,
                    const char *path, ...)
@@ -103,8 +103,8 @@ bool rgbcolor_load(struct section_file *file, struct rgbcolor **prgbcolor,
 }
 
 /**
-   Save an RGB color definition (<colorpath>.red, <colorpath>.green and
-   <colorpath>.blue).
+   Save an RGB color definition (`[colorpath].red`, `[colorpath].green` and
+   `[colorpath].blue`).
  */
 void rgbcolor_save(struct section_file *file,
                    const struct rgbcolor *prgbcolor, const char *path, ...)

common/scriptcore/luascript.cpp

@@ -258,7 +258,8 @@ int luascript_error_vargs(lua_State *L, const char *format, va_list vargs)
 
 /**
    Like script_error, but using a prefix identifying the called lua function:
-     bad argument #narg to '<func>': msg
+
+       bad argument #narg to 'func': msg
  */
 int luascript_arg_error(lua_State *L, int narg, const char *msg)
 {

docs/CMakeLists.txt

@@ -6,15 +6,29 @@ else()
   find_package(Sphinx QUIET)
 endif()
 
-if(SPHINX_FOUND)
-  message(STATUS "Sphinx Found, configuring.")
+find_package(Doxygen)
+
+if (SPHINX_FOUND AND DOXYGEN_FOUND)
+  message(STATUS "Sphinx and Doxygen found, configuring.")
+
   set(SPHINX_SOURCE ${CMAKE_SOURCE_DIR}/docs)
   set(SPHINX_BUILD ${CMAKE_CURRENT_BINARY_DIR})
   set(SPHINX_MAN ${CMAKE_CURRENT_BINARY_DIR}/man)
 
+  # We need to run doxygen before sphinx to update doxygen/tagfile.xml. This
+  # command does it. The output is a dummy one so the command always runs.
+  # doxygen has some level of caching so it doesn't take that long, and
+  # collecting a list of all source files would be cumbersome.
+  add_custom_command(OUTPUT dummy-doxygen
+                     COMMAND Doxygen::doxygen
+                     WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+                     COMMENT "Running Doxygen")
+
+  # This builds the main documentation website.
   add_custom_target(docs
                 COMMAND
                 ${SPHINX_EXECUTABLE} -b html ${SPHINX_SOURCE} ${SPHINX_BUILD}
+                DEPENDS dummy-doxygen
                 WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                 COMMENT "Generating documentation with Sphinx")
 

docs/Coding/ai.rst

@@ -41,7 +41,7 @@ The long-term goals for Freeciv21 :term:`AI` development are:
 Want Calculations
 =================
 
-Build calculations are expressed through a structure called :code:`adv_choice`. This has a variable called
+Build calculations are expressed through a structure called :freeciv21:`adv_choice`. This has a variable called
 "want", which determines how much the :term:`AI` wants whatever item is pointed to by :code:`choice->type`.
 :code:`choice->want` is:
 
@@ -69,36 +69,36 @@ Diplomats, in particular, seem to violate these standards.
 Amortize
 ========
 
-Hard fact: :code:`amortize(benefit, delay)` returns
+Hard fact: :freeciv21:`amortize` returns
 :math:`\texttt{benefit} \times \left(1 - \frac{1}{\texttt{MORT}}\right)^{\texttt{delay}}`.
 
 Speculation: What is better... to receive $10 annually starting in 5 years from now or $5 annually starting
-from this year? How can you take inflation into account? The function :code:`amortize()` is meant to help you
+from this year? How can you take inflation into account? The function :freeciv21:`amortize` is meant to help you
 answer these questions. To achieve this, it re-scales the future benefit in terms of today's money.
 
 Suppose we have a constant rate of inflation, :math:`x` percent. Then in five years $10 will buy as much
 as :math:`10\left(\frac{100}{100 + x}\right)^5` will buy today. Denoting :math:`\frac{100}{100+x}` by
 :math:`q` we get the general formula, :math:`N` dollars, :math:`Y` years from now will be worth
 :math:`N\times q^Y` in today's money. If we receive :math:`N` every year starting :math:`Y` years from now, the
 total amount receivable (in today's money) is :math:`\frac{\,N\,\times\, q^Y}{1 - q}`. This is the sum of
-infinite geometric series. This is exactly the operation that the :code:`amortize()` function performs, the
+infinite geometric series. This is exactly the operation that the :code:`amortize` function performs, the
 multiplication by some :math:`q < 1` raised to power :math:`Y`. Note that the factor :math:`\frac{1}{1 - q}`
 does not depend on the parameters :math:`N` and :math:`Y`, and can be ignored. The connection between the
 :math:`\texttt{MORT}` constant and the inflation rate :math:`x` is given by
 :math:`\frac{\texttt{MORT} - 1}{\texttt{MORT}} = q = \frac{100}{100 + x}`. Thus the current value of
 :math:`\texttt{MORT} = 24` corresponds to the inflation rate, or the rate of expansion of your civilization of
 4.3%
 
-Most likely this explanation is not what the authors of :code:`amortize()` had in mind, but the basic idea is
+Most likely this explanation is not what the authors of :freeciv21:`amortize` had in mind, but the basic idea is
 correct: the value of the payoff decays exponentially with the delay.
 
-The version of amortize used in the military code (:code:`military_amortize()`) remains a complete mystery.
+The version of amortize used in the military code (:freeciv21:`military_amortize`) remains a complete mystery.
 
 
 Estimation of Profit From a Military Operation
 ==============================================
 
-This estimation is implemented by the :code:`kill_desire()` function, which is not perfect, the
+This estimation is implemented by the :freeciv21:`kill_desire` function, which is not perfect, the
 :code:`multi-victim` part is flawed, plus some corrections. In general:
 
 .. math::
@@ -126,7 +126,7 @@ Selecting Military Units
 
 The code dealing with choosing military units to be built and targets for them is especially messy.
 
-Military units are requested in the :code:`military_advisor_choose_build()` function. It first considers the
+Military units are requested in the :freeciv21:`military_advisor_choose_build` function. It first considers the
 defensive units and then ventures into selection of attackers (if home is safe). There are two possibilities
 here: we just build a new attacker or we already have an attacker which was forced, for some reason, to defend.
 In the second case it is easy: we calculate how good the existing attacker is and if it is good, we build a
@@ -135,17 +135,17 @@ defender to free it up.
 Building a brand new attacker is more complicated. First, the :code:`ai_choose_attacker_*` functions are
 called to find the first approximation to the best attacker that can be built here. This prototype attacker
 is selected using very simple :math:`\texttt{attack\_power}\times\texttt{speed}` formula. Then, already in the
-:code:`kill_something_with()` function, we search for targets for the prototype attacker using the
-:code:`find_something_to_kill()` function. Having found a target, we do the last refinement by calling the
-:code:`process_attacker_want()` function to look for the best attacker type to take out the target. This type
-will be our attacker of choice. Note that the :code:`function process_attacker_want()` function has side-effects
+:freeciv21:`kill_something_with` function, we search for targets for the prototype attacker using the
+:freeciv21:`find_something_to_kill` function. Having found a target, we do the last refinement by calling the
+:freeciv21:`process_attacker_want` function to look for the best attacker type to take out the target. This type
+will be our attacker of choice. Note that the function :freeciv21:`process_attacker_want` function has side-effects
 with regards to the Technology selection.
 
 Here is an example:
 
-First the :code:`ai_choose_attacker_land()` function selects a :unit:`Dragoon` because it is strong and fast.
-Then the :code:`find_something_to_kill()` function finds a victim for the (virtual) :unit:`Dragoon`, an enemy
-:unit:`Riflemen` standing right next to the city. Then the :code:`process_attacker_want()` function figures
+First the :freeciv21:`dai_choose_attacker` function selects a :unit:`Dragoon` because it is strong and fast.
+Then the :freeciv21:`find_something_to_kill` function finds a victim for the (virtual) :unit:`Dragoon`, an enemy
+:unit:`Riflemen` standing right next to the city. Then the :freeciv21:`process_attacker_want` function figures
 out that since the enemy is right beside us, it can be taken out easier using an :unit:`Artillery`. It also
 figures that a :unit:`Howitzer` would do this job even better, so bumps up our desire for
 :advance:`Robotics`.
@@ -232,7 +232,7 @@ There are currently seven difficulty levels:
 
 The ``hard`` level is no-holds-barred. ``Cheating`` is the same except that it has ruleset defined extra
 bonuses, while ``normal`` has a number of handicaps. In ``easy``, the :term:`AI` also does random stupid
-things through the :code:`ai_fuzzy()` function. In ``novice`` the :term:`AI` researches slower than normal
+things through the :freeciv21:`ai_fuzzy` function. In ``novice`` the :term:`AI` researches slower than normal
 players. The ``experimental`` level is only for coding. You can gate new code with the ``H_EXPERIMENTAL``
 handicap and test ``experimental`` level :term:`AI`'s against ``hard`` level :term:`AI`'s.
 
@@ -261,7 +261,7 @@ Other handicaps used are:
   ``H_DANGER``      Always thinks its city is in danger.
   ================= =======
 
-For an up-to-date list of all handicaps and their use for each difficulty level see :file:`ai/handicaps.h`.
+For an up-to-date list of all handicaps and their use for each difficulty level see :freeciv21:`handicaps.h`.
 
 
 Things That Need To Be Fixed
@@ -278,15 +278,15 @@ Things That Need To Be Fixed
 * :term:`AI` sometimes believes that wasting a horde of weak military units to kill one enemy is profitable.
 * Stop building shore defense improvements in landlocked cities with a Lake adjacent.
 * Fix the :term:`AI` valuation of :improvement:`Supermarket`. It currently never builds it. See the
-  :code:`farmland_food()` and :code:`ai_eval_buildings()` functions in :file:`advdomestic.cpp`.
+  :freeciv21:`building_advisor_choose` function in :freeciv21:`advbuilding.cpp`.
 * Teach the :term:`AI` to coordinate the units in an attack.
 
 
 Idea Space
 ==========
 
 * Friendly cities can be used as beachheads.
-* The :code:`Assess_danger()` function should acknowledge positive feedback between multiple attackers.
+* The :freeciv21:`assess_danger` function should acknowledge positive feedback between multiple attackers.
 * It would be nice for a bodyguard and charge to meet en-route more elegantly.
-* The :code:`struct choice` should have a priority indicator in it. This will reduce the number of "special"
+* The :freeciv21:`choice` struct should have a priority indicator in it. This will reduce the number of "special"
   want values and remove the necessity to have want capped, thus reducing confusion.