Re: DevDocs support for zephyr docs?
On Thu, Mar 15, 2018 at 1:04 PM, Kinder, David B <david.b.kinder@...> wrote:
No I haven't heard of DevDocs.
I think that the Sphinx content that's rendered by Breathe is a great start (and I've used Breathe to document other projects before, and believe it has good features). However, in my opinion, there are problems with the current output that make it unlikely to be used much in practice by Zephyr developers.
Here are my favorites:
- The header files where the APIs are declared is not clear. What, for example, do I include to use these APIs?
- The output for defines is not useful in the case of macros which are just numbers:
What is K_POLL_TYPE_IGNORE? How do I use it -- are there any examples? Do I just need to read the code to see what its value is? ... but what header is it declared in?
- The lack of consistent cross-referencing is a problem. Let's say I want to use k_thread_access_grant():
What is a struct k_thread; where are its API docs? Note that this is not always a problem, e.g. I do get a reference to k_id_t from here:
In short, the Breathe "doxygengroup" output is not enough on its own to use an API without falling back on the source code. Besides some output (as the K_POLL_TYPE_IGNORE example) just not being useful, other missing critical context includes explanatory text alongside the API docs that describes (or links to more information on) common use cases, motivation, examples, etc.
- a reference book on an API (e.g. https://nostarch.com/download/TLPI_Ch4.pdf)
- other API doc systems, like Java's (e.g. see java.util in https://docs.oracle.com/javase/8/docs/api/)
Or do developers prefer to just "read the code" (header files in particular)?
In my opinion, given the problems above, reading the code (either directly, or using the help of an indexer like cscope, as I prefer) is the only practical choice for developers given the above problems. There's simply not enough information in the doxygengroup output to be useful, at least as it's currently implemented in Breathe and used in Zephyr. That's not ideal IMO -- while some developers always will prefer reading the code, "real" API docs are needed.
Here are some possible alternatives:
- Zephyr could continue to use Doxygen, reST, and Breathe only, but use lower-level Breathe directives like doxygenfunction and doxygendefine to pull in API documentation in appropriate places in a hand-written API description file (probably working with upstream Breathe as necessary to add any missing information and fix issues).
- Add in a publicly available searchable code index like LXR (https://en.wikipedia.org/wiki/LXR_Cross_Referencer, with an example live instance at https://elixir.bootlin.com) or OpenGrok (http://oracle.github.io/opengrok/, example live instance at http://androidxref.com/), and perhaps link to it from the restructuredText (perhaps with a custom directive).
- Combinations of these, etc.