RE: [Devel] FreeType documentation comments

[Graham Asher]

Werner,

thanks for your remarks on documentation comments.

<<<<<<
You should change the editor :-) Using Emacs, an asterisk is
automatically handled as a kind of line comment prefix.  You don't
need to add it; Emacs does this automatically for you.
>>>>>>

I like using the editor built into the Microsoft Visual C++ IDE. I stopped
using EMACS in about 1982, when I finished working with Multics, and I
haven't missed it one bit. But seriously, a style convention should be easy
to use with any editor, and not require a particular one.

<<<<<<
> 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?

Just do it.  I'll take care of formatting (this is my way of reading code).
>>>>>>

This is what I expected. Naturally I am not arrogant enough to expect to be
able to force my way on you, the owners of FreeType, but I think, perhaps in
vain, that if I try to argue the case long enough for a different way of
doing things I might be successful. The marvellous thing is that FreeType
doesn't use Hungarian notation, which is an abomination from the deepest pit
of hell ;-0

And the major design problems in FreeType, which I have argued about
elsewhere, are the exceptionally wide interfaces to functions (almost
everything can be reached via pointer chains from evry function, and almost
nothing is const), awkward conventions involving the ownership of objects
like faces and glyphs, and the difficulty in creating black-box objects.
These structural problems are more important than any matters of notation.

<<<<<<
> 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'm strictly against that.  Regardless of what format the code uses,
uniformity is a main goal.  For example, Stallman will accept patches
for Emacs only if it is exactly formatted as all the other code.
>>>>>>

Actually you already allow some flexibility; no convention is completely
rigid. But I take your point.

<<<<<<
> (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.)

I'm very interested in your complaints since I'm not a native English
speaker (and David isn't either).
>>>>>>

I shouldn't really have said that, because the English is so good, in fact
better than the English of most British and American programmers, that it's
not worth bothering about. The only things I can remember off-hand are the
use of 'x resp. y' for 'x or y respectively', and the use of 'forge' for
'make' or 'create'. But there is nothing that changed the meaning or caused
difficulties in understanding.

Best regards,

Graham