Fixes various Doxygen warnings and other structural defects.
Note: This does not attempt to improve the content of the
documentation; only to improve the syntax and structure of it
and in some cases the consistency.
Change-Id: Ib1915f33edbdbc4558c85565de80dce323193906
Signed-off-by: Chris Luke <chrisy@flirble.org>
Make the struct parser slighty slightly more accomodating of
whitespace in places it has no business being.
Also add missing OS_ID thing to Doxygen makefile.
Change-Id: Id3d198fd926f7a6c2ed40bc2d08907aad5d5ac33
Signed-off-by: Chris Luke <chrisy@flirble.org>
As a step before Doxygen, extract CLI-related struct initializers
from the code and parse that into a summary of the CLI commands
available with the provided help text, such as it is. At the moment
this only renders this into an indexed Markdown file that Doxygen
then picks up but later we can use this information to enrich the
existing VLIB_CLI_COMMAND macro documentor as well as provide
runtime documentation to VPP that is stored on disk outside the
binary image.
Additionally support a comment block immediately prior to
VLIB_CLI_COMMAND CLI command definitions in the form /*? ... ?*/
that can be used to include long-form documentation without having
it compiled into VPP.
Examples of documenting CLI commands can be found in
vlib/vlib/unix/cli.c which, whilst not perfect, should provide a
starting point. Screen captures of sample output can be seen at
https://chrisy.flirble.org/vpp/doxy-cli-example.png and
https://chrisy.flirble.org/vpp/doxy-cli-index.png .
Next, shift the Doxygen root makefile targets to their own Makefile.
The primary reason for this is that the siphon targets do dependency
tracking which means it needs to generate those dependencies whenever
make is run; that is pointless if we're not going to generate any
documentation. This includes the package dependencies since they since
they sometimes unnecessarily interfere with the code build in some cases
at the moment; later we will look to building a Python venv to host the
Python modules we use.
One final remark: In future we may consider deprecating .long_help
in the VLIB_CLI_COMMAND structure entirely but add perhaps .usage_help.
.short_help would be reserved for a summary of the command function
and .usage_help provide the syntax of that command. These changes would
provide great semantic value to the automaticly generated CLI
documentation. I could also see having .long_help replaced by a
mechanism that reads it from disk at runtime with a rudimentary
Markdown/Doxygen filter so that we can use the same text that is used in
the published documentation.
Change-Id: I80d6fe349b47dce649fa77d21ffec0ddb45c7bbf
Signed-off-by: Chris Luke <chrisy@flirble.org>
Also allow a developer to alter the directories scanned at runtime to
facilitate shorter run-times when writing documentation.
Change-Id: I2a09519661a3abe1fbc0cfc294000934852af951
Signed-off-by: Chris Luke <chrisy@flirble.org>
Also add an index of node names
Change-Id: Id65c2e607976d8bad73deb738035a471be077196
Signed-off-by: Dave Barach <dave@barachs.net>
Signed-off-by: Chris Luke <chrisy@flirble.org>
This makes Doxygen think the API definitions are structs which is close
enough to be able to document the API methods.
It also has logic to create an indexed API page but that's disabled for
now because it duplicates the "brief" text twice in the struct doc.
Fixes a minor line numbering issue in filter_c.py.
Change-Id: If380160b73e7c10d999b35a76f55d0e27cbc91cc
Signed-off-by: Chris Luke <chrisy@flirble.org>
- Configures Doxygen.
- Adds a source filter to do magic on our use of the preprocessor to do
constructor stuff to make Doxygen grok it better.
- Adds a convenience helper to the root Makefile.
- Adds a README.md to the root directory (and which Doxygem uses as its
"mainpage".
- Add several other documentative files.
- Currently using SVG for call graphs, though this may have a
load-time performance impact in browsers.
Change-Id: I25fc6fb5bf634319dcb36a7f0e32031921c125ac
Signed-off-by: Chris Luke <chrisy@flirble.org>
