Hi all, With the Apache Mynewt codebase growing steadily, keeping up manually with the API documentation is becoming untenable. So this is a heads-up about moving to doxygen generated API documentation. I initiated the migration of the technical documentation in PR #561 about a month back. An updated PR#619 was merged today so everyone can start documenting the code and providing feedback.
To maintain consistency with the existing website and continue the understandability of code with overviews/explanations/guidelines/tutorials, the technical documentation structure and hierarchy will be preserved i.e. relevant doxygen-generated API will be inserted into overview or explanation document. One change required for this is to rewrite the markdown overview/explanation documents to restructured txt. You can use the tool “pandoc” to convert but the results are not always 100% accurate. So this is what’s on the table: 1) We insert a special comment block for Doxygen in the header files using /** * ... text ... */ Note: We started off with the comment blocks in the .c files but most people seem to prefer the header files. 2) We define a group using the \defgroup command in the special comment block. Example: https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_eventq.c <https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_eventq.c> 3) You can define multiple groups in the same file. For example, the following file has multiple groups: OSMqueue, OSMsys, OSMbuf https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_mbuf.c <https://github.com/apache/mynewt-core/blob/master/kernel/os/src/os_mbuf.c> The documentation files call the appropriate group(s) only. In this example, https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mqueue/mqueue.rst <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mqueue/mqueue.rst> calls OSMqueue https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/msys/msys.rst <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/msys/msys.rst> calls OSMsys https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mbuf/mbuf.rst <https://github.com/apache/mynewt-core/blob/master/docs/os/core_os/mbuf/mbuf.rst> calls OSMbuf 4) We could add a single link for several elements using overarching groups defined using \addtogroup. For example, the entire API for the OS Kernel could be generated using OSKernel. 5) You can build a local copy of the technical docs using the instructions at https://github.com/apache/mynewt-core/tree/master/docs <https://github.com/apache/mynewt-core/tree/master/docs> You can then serve it up locally (e.g. “python -m SimpleHTTPServer 8080”) to review it. One note: It’s better to get rid of the old build artifacts in _build directory before doing another “make htmldocs”. thanks, Aditi
