I hear you that things within core mynewt will stabilize. I agree things will stabilize, except perhaps for HAL as we add more functionality and devices.
I also think we are building something for a community. There will be lots of libraries and apps written by the community to support common stuff like data logging, bluetooth profiles, battery chargers, time synchronizers, display drivers etc. How do we want to help the document what they are providing so its easy to maintain and use by the community. It would seem that extracting docs from their packages is the best options, giving them a framework to add their own docs in markdown along with the auto generated docs from whatever tool we use. I¹m not a big fan of oxygen since it doesn¹t organize C code well and its not always clear what is a public API, but there are tons of doc generators (https://en.wikipedia.org/wiki/Comparison_of_documentation_generators) that may lend a hand. I¹m still against docs with static code samples written in them. Its very hard to make sure they compile if they are not part of a testable project. Its really frustrating to cut and paste and example from a online doc and find that it doesn¹t work. Do we really have the ability to test that in our current help? I¹d way rather see us give a newt command to download samples from an examples package library so we can build them in CI and ensure they at least compile. Paul On 3/4/16, 6:05 PM, "Sterling Hughes" <[email protected]> wrote: > >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
