Re: The Documentation!

[Richard Frith-Macdonald]

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.