On 3/4/16 4:42 PM, [email protected] wrote:
I was writing some documentation today for the hal Apis and had a feeling that
we are making work for ourselves.
Documentation of the interface is important, but I wish we could have some way
to get that from the actual header files. The amount of copying from code to
documentation led me to think that it will become increasingly difficult to get
documentation that truly matches the code. My preference was to link to the
code header file directly, but it would be nice to have some way to process it
for doxygen or other tag language and render within markdown. Any ideas?
Generally, I don't like auto generated docs since they tend to be too verbose
and not very useful, but I fear that hand copying relevant APIs is just too
much work and also is impossible to check for validity.
Second, looking at the code samples, I think they are great, but again, the
likelihood that they remain compilable (if they are now) and useful seems like
it would be an ever increasing burden. Perhaps we should have a samples
repository with simple samples of the various APIs. That way, we can build and
test them with a build server and ensure that they are always working with our
release.
Comments?
What I have seen be OK in the past:
- Doxygen is used to generate just the function prototype and description.
- That is generated as a part of a file, e.g.: os_time_get_def.md
- That file then gets included in the larger file, which contains
more information on how to use that function, e.g. examples, etc.
However, those systems are often pretty custom. i.e. somebody built
them just for the project that generates them.
While we are going to have a fair amount of work now, by 1.0 our APIs
should be _very_ stable and up to date with documentation. The user
documentation should be only externally promised APIs, and those APIs
will only be broken by bumping the major revision. So, I think in a
couple of months this will be less of an issue.
Already libs/os should be fairly stabilized. hw/hal by v0.9 should be
stable as well.
I don't want to do primarily doxygen, because I have had bad experiences
with:
a- You either have tons of comments in littering the source code, OR you
have insufficiently useful documentation in the source code.
b- Documentation should be updated & maintained separately from the
source code itself. You will, eventually have a larger set of people
modifying the documentation than will be modifying your core OS source.
I don't want pull requests on os_sched.c to update the documentation
on our website.
Sterling
