![]() ![]() Assumptions regarding context should be avoided. This is especially true if English is not the readers' native tongue.Īs a consequence documentation should be written with structurally correct English complete with capitalization, sentences and paragraphs where appropriate. This should be avoided since readers of the resulting documentation may find the text halting and lacking context. It is tempting, as developers, to write tersely with the belief that doing so will adequately convey the relevant details. The language of written documentation in VPP is English. For the current development branch this is visible at and for the most recent release branch at. ![]() Whilst it will cover a number of Doxygen features, readers are encouraged to review the Doxygen documentation and in particular special commands page.ĭocumentation is automatically generated after changes are merged into the source repository. This wiki page aims to cover how developers can go about producing documentation. We have Doxygen configured to generate output for items that are not yet documented so that at the very least the names of function parameters or structure members are visible. This is predominantly focused on providing developer-focused information but it can also be used to generate user-focused details.ĭoxygen works by parsing source files and identifying special comment blocks that are adjacent to identifiers in the code. The VPP project currently uses Doxygen as the mechanism to generate documentation. 3.3 Building documentation for a specific directory or file.3.2 Previewing the generated documentation.2.4.5 Adding a markdown file link to the User Documentation page.1.3.4 Describing function-like macros and their parameters.1.3.3 Describing functions and their parameters.1.3.2 Referring to identifiers in the text. ![]() The title of your topic will automatically be inserted.īefore generating the documentation via the DoxyWizard you have to ensure that the path settings within the doxyfile are matching with your environment. Within the MainPage markdown file choose a suitable location and add a reference to your new topic. \defgroup GrpMyTopic This is the title for my [here are your MainPage file At the beginning of the file specify your name and list all contained groups: Within your markdown file define at least one DoxGen group whithin which you place all your descriptions. \include within some other group / page:įor definition of M圜lass see \ref GrpIncludeSourceSomeFileNameĮmbedding your topic into document structure Your topic specific markdown file \defgroup GrpIncludeSourceSomeFileName Header file: GrpSomeParentGroup If you already have well documented (header) files within your source data base then you can simply include them to the generated documentation by defining a corresponding group to which you can put a reference on any place within documentation. ![]() text().as_bool() Īdd selected (header) files to documentation Int numPoints = selectedNode.child( "NumPoints").text().as_int() īool exists = selectedNode.child( "exists"). The generated code sections also support syntax highlighting: Read node values as numeric types // Read several child node values according to their expected types double x = selectedNode.child( "X"). \snippet /TestToolBox/Test/TestXmlCheckWithPugiXml/UsingPugiXml.cpp read node valuesįrom markdown files and connected code snippets Doxygen will generate the following html documentation. Within your textual description in the markdown file add at least a header and a reference to the code snippet by using "\snippet" and the same corresponding tag name as used within your source code: Int numPoints = selectedNode.child("NumPoints").text().as_int() īool exists = selectedNode.child("exists"). Read several child node values according to their expected typesĭouble x = selectedNode.child("X"). The tags for a single code snippet have to be unique within the source file. Mark the found snippets with the same start and end tag "/// ". Within your code search for useful snippets which demonstrate aspects of your topic. regenerate the documentation using DoxyGen and the "doxyfile".edit file "MainPage.markdown" and add a reference to your newly added topic.add references to these tags to your markdown file.add tags at the begin and end of suitable code snippets.choose or create a test project with some code samples demonstrating your topic.write a short text file "SomeTopic.markdown" and store it within Folder "DocProductiveCoding" or "DocUnitTesting" which you can find under path C:/UserData/Gerald/MySwArchive/doc/HowToUse.Embedding your topic into document structure.Add selected (header) files to documentation.Connect markdown file with code snippets. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |