Coding standard for documentation?

[LachlanA]

Greetings all,

The coding standards for Octave are very specific about where to put
whitespace and such, but seem to overlook inline documentation.

Would it be possible to have a standard such that all new functions and
classes have at least a couple of lines at the top explaining why they exist
and how they should be used (such as assumptions about the arguments, who is
responsible for deleting any dynamically allocated objects etc.)?  The same
could apply for multi-line macros, which are used heavily in some files.

Given undocumented code, it is possible to figure out *what* it does, but
not *why* it does it the way it does, such as why a particular wrapper is
needed.

I have thought about trying to add some documentation to existing code, but
it seems odd since everyone else already knows more about the code than I
do.  Perhaps if there is a minimum standard of documentation, it will be
easier to ensure that each function I come across has at least that minimum.

Thoughts?

Lachlan



--
View this message in context: 
http://octave.1599824.n4.nabble.com/Coding-standard-for-documentation-tp4674242.html
Sent from the Octave - Maintainers mailing list archive at Nabble.com.