From 052d57da070239b325fb08d18ae329a1314a5345 Mon Sep 17 00:00:00 2001 From: Corentin Le Molgat Date: Fri, 4 Jul 2025 16:38:43 +0200 Subject: [PATCH] doxygen: Improve C++ ref manual * Had to use absolute paths otherwise `ortools/` conflict with `build/ortools/` * rework Doxygen main page following devsite C++ ref overview. * improve doxygen c++ cache note: doxygen log specify the ideal cache size according to the previous run. --- cmake/cpp.cmake | 15 +++++++- ortools/cpp/Doxyfile.in | 2 +- ortools/cpp/dirs.cpp.dox.in | 76 ++++++++++++++++++++++++++++++++++++ ortools/cpp/main.cpp.dox | 29 -------------- ortools/cpp/main.cpp.dox.in | 77 +++++++++++++++++++++++++++++++++++++ 5 files changed, 168 insertions(+), 31 deletions(-) create mode 100644 ortools/cpp/dirs.cpp.dox.in delete mode 100644 ortools/cpp/main.cpp.dox create mode 100644 ortools/cpp/main.cpp.dox.in diff --git a/cmake/cpp.cmake b/cmake/cpp.cmake index 88dd525a99..f7f8dc9c1f 100644 --- a/cmake/cpp.cmake +++ b/cmake/cpp.cmake @@ -579,7 +579,18 @@ if(BUILD_CXX_DOC) # add a target to generate API documentation with Doxygen find_package(Doxygen REQUIRED) if(DOXYGEN_FOUND) - configure_file(${PROJECT_SOURCE_DIR}/ortools/cpp/Doxyfile.in ${PROJECT_BINARY_DIR}/cpp/Doxyfile @ONLY) + configure_file( + ${PROJECT_SOURCE_DIR}/ortools/cpp/Doxyfile.in + ${PROJECT_BINARY_DIR}/cpp/Doxyfile + @ONLY) + configure_file( + ${PROJECT_SOURCE_DIR}/ortools/cpp/dirs.cpp.dox.in + ${PROJECT_BINARY_DIR}/ortools/dirs.cpp.dox + @ONLY) + configure_file( + ${PROJECT_SOURCE_DIR}/ortools/cpp/main.cpp.dox.in + ${PROJECT_BINARY_DIR}/ortools/main.cpp.dox + @ONLY) file(DOWNLOAD https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.3.4/doxygen-awesome.css ${PROJECT_BINARY_DIR}/cpp/doxygen-awesome.css @@ -595,6 +606,8 @@ if(BUILD_CXX_DOC) ${PROJECT_SOURCE_DIR}/ortools/doxygen/header.html ${PROJECT_SOURCE_DIR}/ortools/doxygen/DoxygenLayout.xml ${PROJECT_SOURCE_DIR}/ortools/cpp/stylesheet.css + ${PROJECT_BINARY_DIR}/ortools/main.cpp.dox + ${PROJECT_BINARY_DIR}/ortools/dirs.cpp.dox WORKING_DIRECTORY ${PROJECT_SOURCE_DIR} COMMENT "Generating C++ API documentation with Doxygen" VERBATIM) diff --git a/ortools/cpp/Doxyfile.in b/ortools/cpp/Doxyfile.in index 4f863f4d6a..9ace0b07e0 100644 --- a/ortools/cpp/Doxyfile.in +++ b/ortools/cpp/Doxyfile.in @@ -472,7 +472,7 @@ TYPEDEF_HIDES_STRUCT = NO # the optimal cache size from a speed point of view. # Minimum value: 0, maximum value: 9, default value: 0. -LOOKUP_CACHE_SIZE = 0 +LOOKUP_CACHE_SIZE = 3 # The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use # during processing. When set to 0 doxygen will based this on the number of diff --git a/ortools/cpp/dirs.cpp.dox.in b/ortools/cpp/dirs.cpp.dox.in new file mode 100644 index 0000000000..ff3775ca71 --- /dev/null +++ b/ortools/cpp/dirs.cpp.dox.in @@ -0,0 +1,76 @@ +/*! @dir @PROJECT_SOURCE_DIR@/ortools/base +This directory provides fundamental utilities for file I/O, logging, and basic data structures that support the other operations research tools. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/init +This directory provides the core library initialization function (InitGoogle) and its language-specific wrappers for +C#, Java, and Python. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/algorithms +Non-graph dedicated algorithms, like our Knapsack solver. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/graph +Graph and Network Flows. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/bop +Google's Boolean Optimization Programming solver (BOP) for binary programs, a specific form of integer programming (MIP). +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/glop +Google's Linear Optimization Programming solver (GLOP) for continuous linear programs (LP). +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/linear_solver +A unified wrapper (MPsolver) around different linear (LP) and integer (MIP) solvers (Glop, Bop, CP-SAT, SCIP, Gurobi, etc.). Use MathOpt instead for new applications. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/math_opt +Our next-generation unified wrapper for LP and MIP solvers. + +@warning Wrappers for C# and Java are not available. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/sat +Our next-gen constraint programming (CP) solver, CP-SAT. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/pdlp +This directory contains PDLP, a library for solving linear programming (LP) and +quadratic programming (QP) problems using first-order methods. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/constraint_solver +Google's deprecated constraint programming (CP) solver. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/routing +Google's routing solver based on the constraint solver. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/packing +Google's packing solver. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/scheduling +Parsers for various standard scheduling problem formats, such as those from the PSP-LIB project scheduling library. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortols/set_cover +Our advanced set-covering solver with innovative greedy algorithms. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/lp_data + This directory contains a rich collection of C++ libraries for handling Linear + Programming (LP) data structures. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/util +Code shared between the different tools and libraries. +*/ + +/*! @dir @PROJECT_SOURCE_DIR@/ortools/flatzinc +This directory holds a parser and solver for the FlatZinc modeling language, enabling it to be solved using the CP-SAT solver. +*/ diff --git a/ortools/cpp/main.cpp.dox b/ortools/cpp/main.cpp.dox deleted file mode 100644 index d530867bd4..0000000000 --- a/ortools/cpp/main.cpp.dox +++ /dev/null @@ -1,29 +0,0 @@ -/*! @file -* @author Laurent Perron -* @author Corentin "Mizux" Le Molgat -*/ - -/*! @mainpage OR-Tools -This is the reference documentation for Google OR-Tools. - -This repository contains several component: - -@li @ref ortools/algorithms "Algorithms" -@li @ref ortools/graph "Graph" -@li @ref ortools/linear_solver "Linear Solver" -@li @ref ortools/math_opt "Math Opt" -@li @ref ortools/glop "GLOP" -@li @ref ortools/sat "SAT" -@li @ref ortools/pdlp "PDLP" -@li @ref ortools/constraint_solver "Constraint Solver" -@li @ref ortools/routing "Routing" -@li @ref ortools/packing "Packing" -@li @ref ortools/scheduling "Scheduling" - -Misc: - -@li @ref ortools/init "init" -@li @ref ortools/base "base" -@li @ref ortools/util "util" - -*/ diff --git a/ortools/cpp/main.cpp.dox.in b/ortools/cpp/main.cpp.dox.in new file mode 100644 index 0000000000..5a02d927ba --- /dev/null +++ b/ortools/cpp/main.cpp.dox.in @@ -0,0 +1,77 @@ +/*! @file +* @author Laurent Perron +* @author Corentin "Mizux" Le Molgat +*/ + +/*! @mainpage OR-Tools +This is the reference documentation for Google OR-Tools. + +This repository contains several components: + + + +
Components table
DirectoriesDescription + +
@ref @PROJECT_SOURCE_DIR@/ortools/base "ortools/base" +Fundamental utilities for the other or-tools components. + +
@ref @PROJECT_SOURCE_DIR@/ortools/init "ortools/init" +Core library initialization functions. + +
@ref @PROJECT_SOURCE_DIR@/ortools/algorithms "ortools/algorithms" +Knapsack solver and related algorithms. + +
@ref @PROJECT_SOURCE_DIR@/ortools/graph "ortools/graph"\n +@ref @PROJECT_BINARY_DIR@/ortools/graph "build/ortools/graph" +Network flow library and related graph algorithms. + +
@ref @PROJECT_SOURCE_DIR@/ortools/bop "ortools/bop"\n +@ref @PROJECT_BINARY_DIR@/ortools/bop "build/ortools/bop" +Google's Boolean Optimization Programming Solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/glop "ortools/glop"\n +@ref @PROJECT_BINARY_DIR@/ortools/glop "build/ortools/glop" +Google's Linear Optimization Programming Solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/linear_solver "ortools/linear_solver"\n +@ref @PROJECT_BINARY_DIR@/ortools/linear_solver "build/ortools/linear_solver" +Unified wrapper for linear (LP) and mixed integer (MIP) solvers. + +
@ref @PROJECT_SOURCE_DIR@/ortools/math_opt "ortools/math_opt"\n +@ref @PROJECT_BINARY_DIR@/ortools/math_opt "build/ortools/math_opt" +Next-generation unified wrapper for LP and MIP solvers. + +
@ref @PROJECT_SOURCE_DIR@/ortools/sat "ortools/sat"\n +@ref @PROJECT_BINARY_DIR@/ortools/sat "build/ortools/sat" +Our next-gen constraint programming (CP) solver, CP-SAT. + +
@ref @PROJECT_SOURCE_DIR@/ortools/pdlp "ortools/pdlp"\n +@ref @PROJECT_BINARY_DIR@/ortools/pdlp "build/ortools/pdlp" +A large-scale linear and quadratic programming solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/constraint_solver "ortools/constraint_solver"\n +@ref @PROJECT_BINARY_DIR@/ortools/constraint_solver "build/ortools/constraint_solver" +Google's legacy Constraint Programming (CP) Solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/routing "ortools/routing"\n +@ref @PROJECT_BINARY_DIR@/ortools/routing "build/ortools/routing" +Google's Routing Solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/packing "ortools/packing"\n +@ref @PROJECT_BINARY_DIR@/ortools/packing "build/ortools/packing" +Packing solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/scheduling "ortools/scheduling"\n +@ref @PROJECT_BINARY_DIR@/ortools/scheduling "build/ortools/scheduling" +Scheduling solver. + +
@ref @PROJECT_SOURCE_DIR@/ortools/set_cover "ortools/set_cover"\n +@ref @PROJECT_BINARY_DIR@/ortools/set_cover "build/ortools/set_cover" +Set Covering Solver + +
@ref @PROJECT_SOURCE_DIR@/ortools/util "ortools/util"\n +@ref @PROJECT_BINARY_DIR@/ortools/util "build/ortools/util" +Code shared between the different tools and libraries. +
+ +*/