Re: Leveraging doxygen in Apache Mynewt API documentation

[Gavin Jefferies <ga...@vmbed.com>]

Hi All,

I'm helping Adithi out with this project. If you are working on APIs
and have any questions regarding how or where to document please let
us know here or on Slack.

In general, API documentation should be in source files in doxygen
format and module guides should be in their repos under the docs
folder. e.g. mynewt-core/docs, mynewt-newt/docs. etc.

Converting from mynewt-site/docs to mynewt-*/docs is a work in
progress and quite manual but hopefully it will be complete prior to
the next major release.

Thanks,
-Gavin





On Tue, Oct 17, 2017 at 1:15 AM, aditi hilbert <ad...@runtime.io> wrote:
> 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
>