RE: [Devel] FreeType documentation comments

[Graham Asher]

David,

thanks for your reply. I'd like to add some further responses:

<<<<<<
The documentation generator
could also be updated to support a minimalistic format like /** ..... */,
but I like
having a big vertical bar of asterisks, since this helps a lot in spotting
comments
in the source code, especially when using a stupid editor like vi that
doesn't
perform syntax highliting, or when printing your code
>>>>>>

I *think* most documentation generators don't need the initial asterisks -
all they need is a comment that starts with "/**". I am very much against
them. I think they look horrible, but my main reason for not wanting them is
that they make it *far* more difficult to edit comments. I really can't work
with any system that requires boxes or initial asterisks - I type fast and I
like to edit extensively as I go along. It should be as easy as possible to
edit comments. This is why all my arguments are aimed at loosening
restrictions and making things easier.

<<<<<<
If you have suggestions for improvements, we'll gladly accept them,
preferrably
as patches ;o)
>>>>>>

Well, I shall be submitting some proposals for new code for FreeType quite
soon, as part of the work I am doing for Artifex, and I would like very much
to do things my way - doesn't everybody? But I realise that the only way I
can do this is through persuasion. I would like also to persuade you and the
other 'owners' of FreeType to allow some flexibility in the code formatting;
I find it very difficult to work with the indenting and spacing conventions
used in the current code, which are not only rather awkward, but I think
unique. I hope everybody will accept my assurance that these criticisms are
not meant to offend, and that I understand that code layout is a matter of
strongly-held personal preference.

<<<<<<
You can already avoid boxes, and I still strongly encourage using a vertical
indent of asterisks.
>>>>>>

Well, I strongly discourage the vertical asterisks... I hope I can persuade
you that we are better off without them.

<<<<<<
On the other hand, there's no way that one can produce
high-quality structured and cross-referenced documentation without using
any kind of tagging.

The fact that '@' is used instead of '\' (standard on JavaDoc and Doxygen)
comes from the fact that the former is a lot quicker to type on my French
keyboard. Again, DocMaker could be trivially changed to support a different
format. Markers/Tags can already be written alternatively as "<Tag>" or
"@Tag:" anyway..
>>>>>>

I agree - but again, *accurate* documentation is better than *inaccurate*
documentation, which is what you get if people forget the tags and think "I
can't be bothered to write [or update] a comment because I'm sure to get the
tagging wrong.". As to what tag to use, I actually agree with you that @ is
the best one.

<<<<<<
So the rule is that the documentation comment goes above the declaration.
Except for internal (static) functions, for example, who generally don't
need a sophisticated formatted comment anyway.
>>>>>>

I concede this point - as long as it goes in one place only. BUT the reasons
for putting the comment above the function body, which we do at Symbian,
are:

1. Headers are easier for humans to read and scan quickly if they are not
cluttered by documentation comments.
2. A programmer spends most of his time working on a function body, not the
function declaration. It is much easier to keep the documentation up to date
if it is next to the part he is working on.

<<<<<<
So, I strongly believe that the quality of documentation has very few
relationships with the tools used to produce it (though this is not
true for its _structure_), or the size of the project involved.
>>>>>>

True - it depends on the procedures and conventions established, and the
culture at the organisation. At Symbian it was perfectly acceptable, and
commonly done, to add a defect to the defect tracking system concerning any
in-source documentation that was missing or incomplete. If people become
used to that way of doing things the battle is half won.

Programmers, who are often rather bad writers, also have to be encouraged to
use complete sentences of grammatical English. (I have a *few* minor
complaints about the English used in FreeType comments, but they are much
better than most of what I have seen in my career.)

Best regards,

Graham