Re: [Devel] FreeType documentation comments

[Werner LEMBERG]

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

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.

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

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

> 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 are welcome.  Meanwhile, I got used to the special code format.

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


    Werner