From c25ced7e11be75f13a8c7a5eb8ccb36545409054 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 13 Jun 2016 18:06:47 +0200 Subject: [PATCH] small pass over the doc --- doc/doxygen/inside_doxygen.doc | 20 +++++++------- doc/doxygen/inside_extending.doc | 47 ++++++++++---------------------- tools/internal/spell_comments.pl | 2 +- tools/internal/spell_dict.txt | 1 + 4 files changed, 27 insertions(+), 43 deletions(-) diff --git a/doc/doxygen/inside_doxygen.doc b/doc/doxygen/inside_doxygen.doc index d69105e902..0aadd25db0 100644 --- a/doc/doxygen/inside_doxygen.doc +++ b/doc/doxygen/inside_doxygen.doc @@ -3,7 +3,7 @@ \tableofcontents -We use doxygen for our documentation. This tool is sometimes anoying +We use doxygen for our documentation. This tool is sometimes annoying but that's the best we've found so far. Remember, we all bitch about doxygen, but at the end of the day, it kinda delivers what we need. So stop bitching about the doc or the tools, and start improving the @@ -12,7 +12,7 @@ documentation text itself. Good documentation is rare and there is not much project of which we can get inspiration. The best exception I know is TikZ and latex-beamer. I'd be so happy if SimGrid documentation could follow -the organisation (and reach half the quality) of the TikZ one. But +the organization (and reach half the quality) of the TikZ one. But anyway. As they say: Documentation is like sex; when it's not good it's still better than nothing and when it's good it's very very good. @@ -25,23 +25,23 @@ possible. \subsection inside_doxygen_module_create Declaring the module to doxygen First declare your sub-module in the corresponding -(project)/doc/doxygen/module-(englobingmodule).doc Two edits are +(project)/doc/doxygen/module-(enclosing module).doc Two edits are needed in this file: -@li Most of the englobing modules (xbt, msg, sd, etc) have a manually +@li Most of the enclosing modules (xbt, msg, sd, etc) have a manually maintained table of contents as content of the module main page, at the top of the corresponding file. You want to add a reference to - your submodule there. For that, simply add something like the + your sub-module there. For that, simply add something like the following. The dash (-) will help building item lists. The ref command requests for a link to your module, that is identified - with the word after that (here, I used xbt_cunit as a submodule + with the word after that (here, I used xbt_cunit as a sub-module identifier. @verbatim - @ref XBT_cunit @endverbatim @li Create your module below in the file as follows. the first world -after the defgroup keyword must be the submodule identifier you used +after the defgroup keyword must be the sub-module identifier you used above. @verbatim /** @defgroup XBT_cunit Unit testing support */ @@ -72,7 +72,7 @@ to add something like this near the top. Any informative stuff is welcomed in the module introduction, on top. This includes examples that the users can copy/paste to fit their needs. If your module is too large to be nicely documented on one -unique page, you may want to split its documentation in submodules. +unique page, you may want to split its documentation in sub-modules. See dynar.h for an example of how to do so. Make sure to only include the public declarations of your module. For @@ -119,11 +119,11 @@ something like the following: @tableofcontents -blabla bla +blah blah blah @section -bliblublo +blah blah blah @subsection <short_name_of_subsection> <title> diff --git a/doc/doxygen/inside_extending.doc b/doc/doxygen/inside_extending.doc index e16c1e6ba8..efb30072e5 100644 --- a/doc/doxygen/inside_extending.doc +++ b/doc/doxygen/inside_extending.doc @@ -3,12 +3,12 @@ \tableofcontents -\section simgrid_dev_guide_model How to add a new model in surf? +\section simgrid_dev_guide_model How to add a new model? The figure below shows the architecture of the SURF layer. This layer is composed of different kinds of models representing the different systems we want to model (i.e., cpu, network, storage, workstation, virtual machine). -A model in simgrid is composed of three classes: Model, Resource and Action +A model in SimGrid is composed of three classes: Model, Resource and Action (\ref SURF_interface "surf_interface.hpp"). \image html surf++.png @@ -27,7 +27,7 @@ that is defined as follows: s_surf_model_description_t surf_network_model_description[] = { -\subsection simgrid_dev_guide_model_implem How to add a new model implementation in surf? +\subsection simgrid_dev_guide_model_implem How to implement a new model? If you want to create a new implementation of a kind of model you must extend the classes of the corresponding interfaces. @@ -64,7 +64,7 @@ s_surf_model_description_t surf_cpu_model_description[] = { }; ~~~~ -\subsection simgrid_dev_guide_model_kind How to add a new kind of model in surf? +\subsection simgrid_dev_guide_model_kind How to add a new kind of model? If you want to create a new kind of model, you must create a new interface where you extend the classes Model, Resource and Action, and then create an @@ -120,7 +120,14 @@ s_surf_model_description_t surf_plugin_description[] = { A simcall is used to go from user mode to kernel mode. There is some sort of popping dance involved, as we want to isolate the user -contextes from their environment (so that they can run in parallel). +contextes from their environment (so that they can run in parallel and +so that we can model-check them). + +In short, just add a line to src/simix/simcalls.in and run the +src/simix/simcalls.py script. It will guide you about how to implement +your simcall. Please keep reading this section (only) if you want to +understand how it goes. + The workflow of a simcall is the following: @@ -162,32 +169,8 @@ generates the following files: The simcall.in file list all the simcalls in sections. A line starting by "##" define a new section which will be replace by a "ifdef" in the generated code. -There is a simcall by line which follow this format: - -~~~~ -Simcall -> Name HasAnswer Res Args -Name -> [a-z0-9_]+ -Has_Answer -> "True" | "False" -Res -> "(" Type MaybeCast ")" -Args -> Args Arg | Arg -Arg -> "(" Name "," Type MaybeCast ")" -Type -> "char" | "const char*" | "int" | "long" | "unsigned char" | "unsigned short" | "unsigned int" | "unsigned long" | "float" | "double" | "void*" | "FPtr" | "const void*" | "size_t" | "sg_size_t" | "void" | "void*" -MaybeCast -> "," Cast | "" -Cast -> [a-z0-9_* ]+ -~~~~ \section simgrid_dev_guide_tag What is How to add a new tag for xml files? -Search for expression \"TUTORIAL: New TAG\". -\verbatim -user@caraja:~/workspace/simgrid/src$ cg "TUTORIAL: New TAG" -0 surf/sg_platf.c 43 /* TUTORIAL: New TAG*/ -1 surf/sg_platf.c 89 /* TUTORIAL: New TAG*/ -2 surf/sg_platf.c 124 /* TUTORIAL: New TAG*/ -3 surf/sg_platf.c 337 /* TUTORIAL: New TAG*/ -4 surf/surfxml_parse.c 769 /* TUTORIAL: New TAG*/ -5 surf/surf_private.h 205 /* TUTORIAL: New TAG*/ -6 surf/surfxml_parseplatf.c 64 /* TUTORIAL: New TAG*/ -7 surf/surfxml_parseplatf.c 85 /* TUTORIAL: New TAG*/ -8 include/simgrid/platf_interface.h 42 /* TUTORIAL: New TAG*/ -\endverbatim -*/ + +You should not do something like that. Please work instead to make XML +avoidable, ie to make the C++ interface nice and usable. diff --git a/tools/internal/spell_comments.pl b/tools/internal/spell_comments.pl index c9659d33f6..961254f84c 100755 --- a/tools/internal/spell_comments.pl +++ b/tools/internal/spell_comments.pl @@ -31,7 +31,7 @@ die "Call this script from its location or from the SimGrid root directory\n" un die "Usage: ". ($DICTFILE eq "./spell_dict.txt"? "./":"tools/internal/")."spell_comments.pl " ."`find ". ($DICTFILE eq "./spell_dict.txt"? "../../":".")." -name '*.[ch]' -o -name '*.hpp' -o -name '*.cpp' |grep -v umpire|grep -v smpi/mpich3-test|grep -v NAS`\n" - unless scalar(@ARGV)>1; + unless scalar(@ARGV)>0; my $total = 0; foreach my $file (@ARGV) { diff --git a/tools/internal/spell_dict.txt b/tools/internal/spell_dict.txt index fd23149d65..d05ad88f0a 100644 --- a/tools/internal/spell_dict.txt +++ b/tools/internal/spell_dict.txt @@ -18,6 +18,7 @@ defgroup dict dicts dontinclude +doxygen DPOR dst dynar -- 2.20.1