[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Devel] FreeType documentation comments
From: |
Werner LEMBERG |
Subject: |
Re: [Devel] FreeType documentation comments |
Date: |
Fri, 24 May 2002 00:42:17 +0200 (CEST) |
> > WHAT IS WRONG
> >
> > 1. The comments are enclosed in unnecessary and in my opinion
> > rather ugly boxes, made of asterisks, that have to be carefully
> > repaired after any edit, and
That we have that many boxes is my `fault'. To have overall
consistency, I intentionally changed all comments to the box format.
> Right now, all new comments I add have the following format:
>
> /**************************************
> *
> * @type: A_Type
> *
> * @description:
> * bla bla bla bla bla
> *
> * @note:
> * foo
> */
Please use this:
/**************************************
*
* @type:
* A_Type
*
* @description:
* bla bla bla bla bla
*
* @note:
* foo
*/
> You can already avoid boxes, and I still strongly encourage using a
> vertical indent of asterisks. 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.
I fully agree.
> 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.
Well, on an English keyboard (which I use) it is not so convenient...
> /****************************************************
> *
> * @function: TT_Load_Any
> *
> * @description:
> * load any font table into a buffer supplied by
> * the caller
> *
> * @input:
> * face :: the face containing the table
> *
> * tag :: that tag of the table to load. Use the
> * value 0 to access the whole font file, else
> * set this parameter to a valid TrueType table
> * tag that you can create with the @FT_MAKE_TAG
> * macro; ...
> */
>
I suggest a slightly different format which is easier to edit if
something changes:
/****************************************************
*
* @function:
* TT_Load_Any
*
* @description:
* Load any font table into a buffer supplied by
* the caller.
*
* @input:
* face ::
* The face containing the table.
*
* tag ::
* The tag of the table to load. Use
* value 0 to access the whole font file, else
* set this parameter to a valid TrueType table
* tag that you can create with the @FT_MAKE_TAG
* macro; ...
*/
If you agree, I will slowly convert all comments to that format; I
think it is an interesting exercise to write a small sed program to do
that semi-automatically :-)
> 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.
Some years ago I've sent some test output from my (oold) c2cweb tool
which generates pretty-printed TeX output. cweb parses the C code to
a certain extent, so it can do very clever things; the most useful
feature is an index of all used variables and functions. In case you
are interested I can prepare an example again.
Werner
- Re: [Devel] font format corner cases, (continued)
[Devel] FreeType documentation comments, Graham Asher, 2002/05/23
- RE: [Devel] FreeType documentation comments, Graham Asher, 2002/05/23
- [Devel] "interface" still exists in FreeType header, Graham Asher, 2002/05/23
- Re: [Devel] FreeType documentation comments, David Turner, 2002/05/23
- Re: [Devel] FreeType documentation comments,
Werner LEMBERG <=
- RE: [Devel] FreeType documentation comments, Graham Asher, 2002/05/24
- Re: [Devel] FreeType documentation comments, Werner LEMBERG, 2002/05/24
- Re: [Devel] FreeType documentation comments, Artur Zaprzala, 2002/05/24
- Re: [Devel] FreeType documentation comments, Keith Harwood, 2002/05/26
- Re: [Devel] FreeType documentation comments, Artur Zaprzala, 2002/05/27
- Re: [Devel] FreeType documentation comments, Keith Harwood, 2002/05/28
RE: [Devel] FreeType documentation comments, Graham Asher, 2002/05/25
Re: [Devel] FreeType documentation comments, Werner LEMBERG, 2002/05/25
[Devel] Selecting the Unicode charmap by default, Graham Asher, 2002/05/24
Re: [Devel] Selecting the Unicode charmap by default, 山内 英敏, 2002/05/24