|
Rockbox mail archiveSubject: Re: API documentationRe: API documentation
From: Marcin Bukat <marcin.bukat_at_gmail.com>
Date: Sat, 11 Dec 2010 13:26:47 +0100 Opinions gathered here and on IRC boils down to the conclusion that inline documentation is considered an option but there are concerns if doxygen is the right tool to use. The first step to use concept of inline documentation is to state the rule to add comments (in particular format suitable for parsers) to the parts of code being touched. This is independent from the tool used later to parse this. Moreover comments are a good thing so we will only gain in stating such rule even if we consider to not use doxygen-like tool at the end. Looking at the doxygen documentation I think the most suitable format for inline documentation is javadoc style: /** Shor descritpion. * * Detailed description */ This looks quite natural and follows our rule to use C-style comments. To conclude, I think stating the rule to put such comments in .h files will be pure benefit. Marcin Bukat (wodz) Received on 2010-12-11 Page template was last modified "Tue Sep 7 00:00:02 2021" The Rockbox Crew -- Privacy Policy |