From 8de7a90b044d2c8cf008e498f533cd7131c9f106 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Sun, 22 May 2016 22:14:44 +0200 Subject: [PATCH 1/1] Reorganize the documentation The skeleton now has to be fleshed --- doc/Doxyfile.in | 26 +++++++++----- doc/doxygen/advanced.doc | 13 ------- doc/doxygen/community.doc | 6 ++++ .../{help.doc => community_contact.doc} | 2 +- doc/doxygen/community_extend.doc | 12 +++++++ ...ontributing.doc => community_giveback.doc} | 2 +- doc/doxygen/index.doc | 35 ++++++++++++------- doc/doxygen/inside.doc | 5 ++- doc/doxygen/install.doc | 4 +-- doc/doxygen/models.doc | 10 ++++++ doc/doxygen/module-index.doc | 6 +--- doc/doxygen/module-msg.doc | 2 +- doc/doxygen/module-sd.doc | 5 +-- doc/doxygen/module-smpi.doc | 6 ++-- doc/doxygen/module-trace.doc | 19 +++++----- doc/doxygen/options.doc | 2 +- doc/doxygen/outcomes.doc | 10 ++++++ doc/doxygen/outcomes_MC.doc | 6 ++++ doc/doxygen/outcomes_logs.doc | 6 ++++ .../{tracing.doc => outcomes_vizu.doc} | 7 ++-- doc/doxygen/scenario.doc | 13 +++++++ doc/doxygen/uhood.doc | 9 +++++ examples/msg/README.doc | 4 +-- src/instr/instr_interface.cpp | 8 ++--- src/msg/msg_gos.cpp | 2 +- tools/cmake/DefinePackages.cmake | 17 ++++++--- 26 files changed, 161 insertions(+), 76 deletions(-) delete mode 100644 doc/doxygen/advanced.doc create mode 100644 doc/doxygen/community.doc rename doc/doxygen/{help.doc => community_contact.doc} (97%) create mode 100644 doc/doxygen/community_extend.doc rename doc/doxygen/{contributing.doc => community_giveback.doc} (98%) create mode 100644 doc/doxygen/models.doc create mode 100644 doc/doxygen/outcomes.doc create mode 100644 doc/doxygen/outcomes_MC.doc create mode 100644 doc/doxygen/outcomes_logs.doc rename doc/doxygen/{tracing.doc => outcomes_vizu.doc} (98%) create mode 100644 doc/doxygen/scenario.doc create mode 100644 doc/doxygen/uhood.doc diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index fce8f59ed8..7835adcc63 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -646,23 +646,31 @@ INPUT = doxygen/index.doc \ doxygen/getting_started.doc \ doxygen/install.doc \ doxygen/application.doc \ - doxygen/tutorial.doc \ - doxygen/examples.doc \ - doxygen/platform.doc \ + doxygen/bindings.doc \ + doxygen/platform.doc \ + doxygen/models.doc \ + doxygen/pls.doc \ + doxygen/scenario.doc \ doxygen/deployment.doc \ doxygen/options.doc \ - doxygen/help.doc \ - doxygen/advanced.doc \ - doxygen/pls.doc \ - doxygen/bindings.doc \ + doxygen/outcomes.doc \ + doxygen/outcomes_logs.doc \ + doxygen/outcomes_vizu.doc \ + doxygen/outcomes_MC.doc \ + doxygen/tutorial.doc \ + doxygen/examples.doc \ + doxygen/uhood.doc \ doxygen/inside.doc \ doxygen/inside_doxygen.doc \ doxygen/inside_extending.doc \ doxygen/inside_cmake.doc \ doxygen/inside_tests.doc \ doxygen/inside_release.doc \ - doxygen/contributing.doc \ - doxygen/tracing.doc \ + doxygen/community.doc \ + doxygen/community_contact.doc \ + doxygen/community_contributing.doc \ + doxygen/community_extend.doc \ + doxygen/community_giveback.doc \ doxygen/FAQ.doc \ doxygen/module-msg.doc \ doxygen/module-sd.doc \ diff --git a/doc/doxygen/advanced.doc b/doc/doxygen/advanced.doc deleted file mode 100644 index 1ca3d42ee3..0000000000 --- a/doc/doxygen/advanced.doc +++ /dev/null @@ -1,13 +0,0 @@ -/*! @page advanced Advanced Topics - -This page does not exist yet. Writing an acceptable user documentation -is already difficult, but writing a good documentation for advanced -users is near to impossible. In the meanwhile, please refer to the -tutorials on the project web page, looking for the "SimGrid::Internals" -tutorials. - -- @subpage bindings -- @subpage pls -- @subpage tracing - -*/ diff --git a/doc/doxygen/community.doc b/doc/doxygen/community.doc new file mode 100644 index 0000000000..2b61e435c8 --- /dev/null +++ b/doc/doxygen/community.doc @@ -0,0 +1,6 @@ +/** +@page community The SimGrid Community + +TBD + +*/ \ No newline at end of file diff --git a/doc/doxygen/help.doc b/doc/doxygen/community_contact.doc similarity index 97% rename from doc/doxygen/help.doc rename to doc/doxygen/community_contact.doc index 5e2b937703..3eea121835 100644 --- a/doc/doxygen/help.doc +++ b/doc/doxygen/community_contact.doc @@ -1,4 +1,4 @@ -/*! @page contact Contact us +/*! @page community_contact Contact us If you are new to the SimGrid framework, you should first strive at reading the current documentation and studying the provided examples. diff --git a/doc/doxygen/community_extend.doc b/doc/doxygen/community_extend.doc new file mode 100644 index 0000000000..ecf8efe4b7 --- /dev/null +++ b/doc/doxygen/community_extend.doc @@ -0,0 +1,12 @@ +/** +@page community_extend Extending SimGrid and Contributed Code + +TBD + + - Contribute a Platform file + - Contribute a Plugin + - Contribute a Routing Schema + + - the current Contributed section from the website + +*/ \ No newline at end of file diff --git a/doc/doxygen/contributing.doc b/doc/doxygen/community_giveback.doc similarity index 98% rename from doc/doxygen/contributing.doc rename to doc/doxygen/community_giveback.doc index ab8019bbdd..94c276df57 100644 --- a/doc/doxygen/contributing.doc +++ b/doc/doxygen/community_giveback.doc @@ -1,4 +1,4 @@ -/*! @page contributing Giving back to SimGrid +/*! @page community_giveback Giving back to SimGrid @tableofcontents diff --git a/doc/doxygen/index.doc b/doc/doxygen/index.doc index 878274d5dd..2f98047d60 100644 --- a/doc/doxygen/index.doc +++ b/doc/doxygen/index.doc @@ -14,23 +14,32 @@ - @subpage install - @subpage application - @subpage MSG_API - - @subpage platform + - @subpage SD_API + - @subpage SMPI_API + - @subpage bindings +- @subpage platform + - @subpage models + - @subpage pls +- @subpage scenario - @subpage deployment - @subpage options +- @subpage outcomes + - @subpage outcomes_logs + - @subpage outcomes_vizu + - @subpage outcomes_MC +- Use Cases + - Energy, Clouds + - Scalability Tweaks - @subpage tutorial - @subpage examples -- @subpage advanced - - @ref bindings - - @ref pls - - @ref tracing -- @subpage inside - - @ref inside_tests - - @ref inside_doxygen - - @ref inside_extending - - @ref inside_cmake - - @ref inside_release -- @subpage contributing - - @ref contact +- @subpage uhood + - Simulating Resource Sharing + - Context Switching + - @subpage inside +- @subpage community + - @subpage community_contact + - @subpage community_giveback + - @subpage community_extend - @subpage FAQ @htmlonly diff --git a/doc/doxygen/inside.doc b/doc/doxygen/inside.doc index 19284c0669..99a9759c8a 100644 --- a/doc/doxygen/inside.doc +++ b/doc/doxygen/inside.doc @@ -1,7 +1,6 @@ -/*! @page inside SimGrid Developer Guide +/*! @page inside Coding Standard and Project Architecture -This page does not exist yet, sorry. We are currently refurbishing the -user documentation -- the internal documentation will follow (FIXME). +TBD: Coding Standard There is two main things you want to know about the internals of SimGrid. First, you need to understand the component organization, as diff --git a/doc/doxygen/install.doc b/doc/doxygen/install.doc index 721f9edb29..dd3d673d49 100644 --- a/doc/doxygen/install.doc +++ b/doc/doxygen/install.doc @@ -50,7 +50,7 @@ will appear on the top of the resulting page. @ref contributing_bugs "you should report".\n If your system is actually not supported, you should compile your own jarfile @ref install_src "by compiling SimGrid" on your - machine. If you feel so, @ref contact "contact us" so that we add + machine. If you feel so, @ref community_contact "contact us" so that we add your architecture to the list. - **Library not found: boost-context**.\n @@ -253,7 +253,7 @@ Actually your help is welcome. The drawback of MinGW-64 is that the produced DLL are not compatible with MS Visual C. clang-cl sounds promising to fix this. If you get something working, please -@ref contact "tell us". +@ref community_contact "tell us". @subsubsection install_src_32bits 32 bits Builds on Multi-arch Linux diff --git a/doc/doxygen/models.doc b/doc/doxygen/models.doc new file mode 100644 index 0000000000..caed4c6b40 --- /dev/null +++ b/doc/doxygen/models.doc @@ -0,0 +1,10 @@ +/** +@page models SimGrid Models + +TBD + + - Main existing models (contention, cste, LM07) + - Main concepts (Routing, LMM) + link to the papers + - How to switch on the command line + +*/ \ No newline at end of file diff --git a/doc/doxygen/module-index.doc b/doc/doxygen/module-index.doc index 607bd988a0..cfecff095d 100644 --- a/doc/doxygen/module-index.doc +++ b/doc/doxygen/module-index.doc @@ -1,7 +1,3 @@ -/** \defgroup SMPI_API SMPI - \brief Programming environment for the simulation of MPI applications -*/ - /** @defgroup XBT_API XBT @brief The core toolbox of SimGrid, containing useful datatypes and friends @@ -23,7 +19,7 @@ The API enables the declaration of categories and a function to associate them to the tasks (MSG and SD). The tasks that are not classified according to a category are not traced. If no categories are specified, simulations can still be traced using a special -parameter in the command line (see \ref tracing for details). +parameter in the command line (see \ref outcomes_vizu for details). */ diff --git a/doc/doxygen/module-msg.doc b/doc/doxygen/module-msg.doc index 6212e569cb..0637b31a97 100644 --- a/doc/doxygen/module-msg.doc +++ b/doc/doxygen/module-msg.doc @@ -1,5 +1,5 @@ /** -@defgroup MSG_API MSG: Simple API for CSP Algorithms +@defgroup MSG_API MSG: Simulate CSP Algorithms @brief Simple programming environment MSG is a simple API to write algorithms organized with Concurrent diff --git a/doc/doxygen/module-sd.doc b/doc/doxygen/module-sd.doc index 0bb49538cf..25c855fc52 100644 --- a/doc/doxygen/module-sd.doc +++ b/doc/doxygen/module-sd.doc @@ -1,5 +1,6 @@ -/** @defgroup SD_API SimDag for DAG applications - @brief Programming environment for DAG applications +/** +@defgroup SD_API SimDag: Simulate DAG algorithms +@brief Programming environment for DAG applications SimDag provides functionnalities to simulate parallel task scheduling arranged in DAGs (Direct Acyclic Graphs). Only centralized algorithms diff --git a/doc/doxygen/module-smpi.doc b/doc/doxygen/module-smpi.doc index 65b0f29d5c..b4cb0ab9a5 100644 --- a/doc/doxygen/module-smpi.doc +++ b/doc/doxygen/module-smpi.doc @@ -1,5 +1,7 @@ -/** @addtogroup SMPI_API - +/** +@defgroup SMPI_API SMPI: Semulate real MPI applications +@brief Programming environment for the simulation of MPI applications + This programming environment enables the study of MPI application by emulating them on top of the SimGrid simulator. This is particularly interesting to study existing MPI applications within the comfort of diff --git a/doc/doxygen/module-trace.doc b/doc/doxygen/module-trace.doc index de01c4a183..6b98031eb9 100644 --- a/doc/doxygen/module-trace.doc +++ b/doc/doxygen/module-trace.doc @@ -6,15 +6,16 @@ - \ref TRACE_mark - \ref TRACE_user_variables -\defgroup TRACE_category Tracing categories -\ingroup TRACE_API -\brief Functions to declare tracing categories. +@{ + + @defgroup TRACE_category Tracing categories + @brief Functions to declare tracing categories. -\defgroup TRACE_mark Tracing marks -\ingroup TRACE_API -\brief Functions to declare and create tracing marks. + @defgroup TRACE_mark Tracing marks + @brief Functions to declare and create tracing marks. -\defgroup TRACE_user_variables Tracing user variables -\ingroup TRACE_API -\brief Functions to declare and define user variables associated to resources. + @defgroup TRACE_user_variables Tracing user variables + @brief Functions to declare and define user variables associated to resources. + +@} */ \ No newline at end of file diff --git a/doc/doxygen/options.doc b/doc/doxygen/options.doc index 27e205df85..f45e1f5671 100644 --- a/doc/doxygen/options.doc +++ b/doc/doxygen/options.doc @@ -636,7 +636,7 @@ which value is either: \section options_tracing Configuring the tracing subsystem -The \ref tracing "tracing subsystem" can be configured in several +The \ref outcomes_vizu "tracing subsystem" can be configured in several different ways depending on the nature of the simulator (MSG, SimDag, SMPI) and the kind of traces that need to be obtained. See the \ref tracing_tracing_options "Tracing Configuration Options subsection" to diff --git a/doc/doxygen/outcomes.doc b/doc/doxygen/outcomes.doc new file mode 100644 index 0000000000..cd395e04c3 --- /dev/null +++ b/doc/doxygen/outcomes.doc @@ -0,0 +1,10 @@ +/** +@page outcomes Simulation Outcomes + +TBD + + - Logs + - Visualisation and post-mortem statistics analysis + - Model-Checking + +*/ \ No newline at end of file diff --git a/doc/doxygen/outcomes_MC.doc b/doc/doxygen/outcomes_MC.doc new file mode 100644 index 0000000000..551bc134c1 --- /dev/null +++ b/doc/doxygen/outcomes_MC.doc @@ -0,0 +1,6 @@ +/** +@page outcomes_MC Model-Checking + +TBD + +*/ \ No newline at end of file diff --git a/doc/doxygen/outcomes_logs.doc b/doc/doxygen/outcomes_logs.doc new file mode 100644 index 0000000000..3dd66c0408 --- /dev/null +++ b/doc/doxygen/outcomes_logs.doc @@ -0,0 +1,6 @@ +/** +@page outcomes_logs Simulation Logging + +TBD + +*/ \ No newline at end of file diff --git a/doc/doxygen/tracing.doc b/doc/doxygen/outcomes_vizu.doc similarity index 98% rename from doc/doxygen/tracing.doc rename to doc/doxygen/outcomes_vizu.doc index 3b25b06c01..2673e2f546 100644 --- a/doc/doxygen/tracing.doc +++ b/doc/doxygen/outcomes_vizu.doc @@ -1,7 +1,10 @@ -/*! \page tracing Tracing Simulations +/*! \page outcomes_vizu Visualization and Statistical Analysis +SimGrid comes with an extensive support to trace and register what +happens during the simulation, so that it can be either visualized or +statistically analysed after the simulation. -Tracing is widely used to observe and understand the behavior of +This tracing is widely used to observe and understand the behavior of parallel applications and distributed algorithms. Usually, this is done in a two-step fashion: the user instruments the application and the traces are analyzed after the end of the execution. The analysis diff --git a/doc/doxygen/scenario.doc b/doc/doxygen/scenario.doc new file mode 100644 index 0000000000..7fd0d5e6ae --- /dev/null +++ b/doc/doxygen/scenario.doc @@ -0,0 +1,13 @@ +/** +@page scenario Describing the experimental scenario + +TBD + +Main concepts: + + - Deployment file + - Availability and state profiles + - Reproducible random number generation + - Command line options, in particular on the model switching + +*/ \ No newline at end of file diff --git a/doc/doxygen/uhood.doc b/doc/doxygen/uhood.doc new file mode 100644 index 0000000000..59963ed6ea --- /dev/null +++ b/doc/doxygen/uhood.doc @@ -0,0 +1,9 @@ +/*! @page uhood Under the Hood + +TBD + + - Simulation Loop, LMM, sharing -> papers + - Context Switching, privatization -> papers + - @subpage inside + +*/ diff --git a/examples/msg/README.doc b/examples/msg/README.doc index 57baa42e16..5b6e08991a 100644 --- a/examples/msg/README.doc +++ b/examples/msg/README.doc @@ -60,7 +60,7 @@ shipped in the archive: until all activities in a given set have completed. - Waiting for the first completed communication in a set. - @ref examples/msg/async-waitall/async-waitany.c\n + @ref examples/msg/async-waitany/async-waitany.c\n The @ref MSG_comm_waitany function is useful when you want to block until one activity of the set completes, no matter which terminates first. @@ -275,7 +275,7 @@ top of the example file). @example examples/msg/async-wait/async-wait.c @example examples/msg/async-waitall/async-waitall.c -@example examples/msg/async-waitall/async-waitany.c +@example examples/msg/async-waitany/async-waitany.c @example examples/msg/process-create/process-create.c @example examples/msg/process-suspend/process-suspend.c diff --git a/src/instr/instr_interface.cpp b/src/instr/instr_interface.cpp index 6c03941593..3b7ec27783 100644 --- a/src/instr/instr_interface.cpp +++ b/src/instr/instr_interface.cpp @@ -50,7 +50,7 @@ static xbt_dynar_t instr_dict_to_dynar (xbt_dict_t filter) * task category. Tasks that do not belong to a category are not traced. The color for the category that is being * declared is random. This function has no effect if a category with the same name has been already declared. * - * See \ref tracing for details on how to trace the (categorized) resource utilization. + * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * * \param category The name of the new tracing category to be created. * @@ -68,10 +68,10 @@ void TRACE_category(const char *category) * So, to specify a red color, pass "1 0 0" as color parameter. A light-gray color can be specified using "0.7 0.7 0.7" * as color. This function has no effect if a category with the same name has been already declared. * - * See \ref tracing for details on how to trace the (categorized) resource utilization. + * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * * \param category The name of the new tracing category to be created. - * \param color The color of the category (see \ref tracing to + * \param color The color of the category (see \ref outcomes_vizu to * know how to correctly specify the color) * * \see MSG_task_set_category, SD_task_set_category @@ -115,7 +115,7 @@ void TRACE_category_with_color (const char *category, const char *color) * This function should be used to get categories that were already declared with #TRACE_category or with * #TRACE_category_with_color. * - * See \ref tracing for details on how to trace the (categorized) resource utilization. + * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * * \return A dynar with the declared categories, must be freed with xbt_dynar_free. * diff --git a/src/msg/msg_gos.cpp b/src/msg/msg_gos.cpp index 1867677b68..becc04b412 100644 --- a/src/msg/msg_gos.cpp +++ b/src/msg/msg_gos.cpp @@ -931,7 +931,7 @@ int MSG_task_listen_from(const char *alias) * parameter category must contain a category that was previously declared with the function #TRACE_category * (or with #TRACE_category_with_color). * - * See \ref tracing for details on how to trace the (categorized) resource utilization. + * See \ref outcomes_vizu for details on how to trace the (categorized) resource utilization. * * \param task the task that is going to be categorized * \param category the name of the category to be associated to the task diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake index 1fb2900bd7..506d7c6347 100644 --- a/tools/cmake/DefinePackages.cmake +++ b/tools/cmake/DefinePackages.cmake @@ -786,15 +786,17 @@ set(DOC_SOURCES doc/triva-time_interval.svg doc/doxygen/FAQ.doc - doc/doxygen/advanced.doc doc/doxygen/application.doc doc/doxygen/bindings.doc - doc/doxygen/contributing.doc + doc/doxygen/community.doc + doc/doxygen/community_contact.doc + doc/doxygen/community_extend.doc + doc/doxygen/community_giveback.doc doc/doxygen/deployment.doc + doc/doxygen/examples.doc doc/doxygen/footer.html doc/doxygen/getting_started.doc doc/doxygen/header.html - doc/doxygen/help.doc doc/doxygen/index.doc doc/doxygen/inside.doc doc/doxygen/inside_tests.doc @@ -804,6 +806,7 @@ set(DOC_SOURCES doc/doxygen/inside_release.doc doc/doxygen/install.doc doc/doxygen/tutorial.doc + doc/doxygen/models.doc doc/doxygen/module-msg.doc doc/doxygen/module-sd.doc doc/doxygen/module-simix.doc @@ -813,11 +816,15 @@ set(DOC_SOURCES doc/doxygen/module-xbt.doc doc/doxygen/module-index.doc doc/doxygen/options.doc + doc/doxygen/outcomes.doc + doc/doxygen/outcomes_logs.doc + doc/doxygen/outcomes_MC.doc + doc/doxygen/outcomes_vizu.doc doc/doxygen/platform.doc doc/doxygen/pls.doc + doc/doxygen/scenario.doc doc/doxygen/stylesheet.css - doc/doxygen/tracing.doc - doc/doxygen/examples.doc + doc/doxygen/uhood.doc doc/manpage/smpicc.1 doc/manpage/smpicxx.1 -- 2.20.1