![]() ![]() for a C code block.ĭescribing functions and their parametersįunctions are typically documented with a docblock immediately before the function definition. Post-identifier comment blocks are given with /**.These are documentation blocks that come immediately before the code that they provide documentation for.Pre-identifier comment blocks are signified with /**.Whilst any will work, VPP as a project has adopted the following as conventions: It provides several ways to indicate both of these things. To promote consistency both in the VPP source code and in the generated text, these are the conventions VPP have adopted for writing documentation.ĭoxygen requires the use of specially marked comment blocks to identify documentation and recognizes several special commands inside those blocks. Since global variables are evil but are sometimes necessary we should encourage developers to justify their existence, to apologize to future programmers and beg their forbearance for the indiscretion. It is very apparent in the generated documentation when developers only partially document these things. Similarly enumerations should have documentation both for the enumeration as a whole as well as individual items defined by it. For example, structures (and unions) require documentation describing both the structure itself as well as all of its members. Thus it is recommended that such items not be skipped from consideration merely because the meaning seems plain. In general, even though the purpose of an item may be obvious from its name, when rendered as documentation this implicit meaning is not always forthcoming. However static and inline functions in header files are much more widely visible and should be documented. In general, static and inline functions within modules are not visible outside that module and thus adding a documentation block may be of limited value (with exceptions, such as when used for function pointers for consumption elsewhere) though this does not excuse a developer from writing useful comments. Anything else that may be of use to the developer who comes after you.At the moment most API documentation just describes the parameters better description of what API calls do is necessary in many cases.These will eventually be extracted for automatic documentation.*_main_t and other primary data structures used for interacting with modules.FIB and other centralized data store and lookup mechanisms.Node and feature lookup, insertion or other manipulation functions.Widely-used library functions, structures and pre-processor macros.In an ideal world we would document everything however given the realities of life and open source projects here are a list of items that should be prioritized for documenting and where the better the documentation the better able VPP is to mature: Spelling mistakes and grammar are easily fixed later structure and context are much harder to fill in. 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. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |