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? Paul
