Re: [ft-devel] Markdown Documentation in header files

[Werner LEMBERG]

>> I don't object.  However, it's a lot of work to walk over the whole
>> documentation to unify the comment formats, which is dull work I
>> was always too lazy for doing.
> 
> My plan is to automatically do this with a program.

OK, fine.  BTW, if you are going to convert all comments, please
convert to the `light' format, using address@hidden' instead of `<foo>' for
tags (the latter can be dropped completely then):

 /******************************************************************
  *
  * @enum:
  *    FT_VALIDATE_OTXXX
  *
  * @description:
  *    A list of bit-field constants used with @FT_OpenType_Validate
  *    to indicate which OpenType tables should be validated.
  *
  * @values:
  *    FT_VALIDATE_BASE ::
  *      Validate BASE table.
  *
  */

This makes all header files smaller and easier to format.

>> In particular, it's not clear to me what happens with stuff between
>> a closing </section> and the next <section>.  Right now, a section
>> is everything until the next <section> tag appears.
> 
> This is to maintain consistency, if we're using markup tags.
> Please have a look at the attached file 'comments_example_1.h'
> This uses ending tags for sections, functions and other parts.

No, no, no, please not this route.  The </...> tags are all redundant!
The less typing for the programmer, the better.

> I haven't thought much about this, but because there aren't nested
> tags right now, and I don't see any such requirement in the
> foreseeable future (is there?), I think we can do fine without any
> closing tags.

Yep.


    Werner