On 23 Jan 2007, at 18:00, Stefan Bidigaray wrote:
As some of you may know, I've been slowly writing documentation for
the GUI library, and I've become amazed at the utter chaos of the
documentation. Not as in things are wrong, but as they are
written. Two things that seem to sometimes slow me down (not a
lot) is the fact that sometimes the documentation is written in
the .m files and some times in the .h files. Another thing, which
is more of a pet peeve of mine is the fact that some writting are
done with * at the beginning of the line, which greatly helps when
trying to skip over stuff that is already documentation and some
don't, like this:
/** Blah blah blah
* blah blah blah
*/
An aesthetic thing which helps readability for me, but I like to see
the asterisks lining up (ie one space in from start of line if the
slash is at the start of the line) and always do documentation like
that, so you will find that it is the predominant documentation
style. I also think it helps to try to make the documentation in the
header files as readable as possible ... and as it's most common
practice in ObjC, C, and C++ programs to line up the asterisks, it
probably makes it most readable for most people (where it makes a
difference).
Anyway, what I'd like to do, is as I go through all the different
classes, if it would be OK if I changed thing stuff. That is, move
all documentation to .h files, which in my opinion makes more sense
having it there. And also cleaning up by inserting * at the
beginning of all lines that document anything. Also whatever else
I see that could help reading the documentation in the source/
header files. The reason I ask is because it's going to create
huge .patch/.diff/(whatever you want to call it) files.
I would support the move of documentation from .m to .h files, and
insertion of neatly lined up asterisks where missing, to make blocks
of comments look good.
_______________________________________________
Discuss-gnustep mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/discuss-gnustep
