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

[Werner LEMBERG]

>> (1)
>> There are two formats for *markup tags*:
>>
>> <Section> and @Section
>>
>> I suggest replacing these with a single format that is easy to
>> write.
>
> That sounds nice, as it will make 'docmaker' to handle less cases,
> as of now two are being supported.

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.

>> (3)
>> For each section of a comment block, currently there is only a
>> starting tag, like <Section>.  I suggest adding an ending tag like
>> </Section> so that anything between these tags can be directly
>> parsed as markdown.
>
> Agree, with the fact it will provide more freedom of having
> discontinuous blocks the same section.  And no more comment symbols
> like "/* */" or "*" in each line.

Again, I don't object.  However, I would like to see some examples
before deciding this.  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.

>> (4)
>> Code blocks in comments are currently wrapped in curly brackets.
>> This can be either replaced with the triple backticks (```) in the
>> documentation itself, or this replacement can be handled by the
>> modified docmaker depending on the requirement of the to-html
>> converter.

Using ```c directly is OK with me.  We sometimes have pseudo code
samples that aren't valid C code; for such cases we could then
directly use a ``` block (without a trailing c) to avoid potential
highlighting errors.


    Werner