[Lazarus] Adding Notes in FPDoc

[Michael Van Canneyt]

On Sat, 11 Feb 2012, Hans-Peter Diettrich wrote:

> Michael Van Canneyt schrieb:
>
>> Seeing the discussions about annotating the documentation created by FPDoc, 
>> I added support for notes.
>> (revision 20304)
>
> Thanks :-)
>
>> In short:
>> 
>> At the level of the <module>, <topic> and <element> tags, you can now 
>> include a <notes> tag.
>> 
>> Within the <notes> tag, you can include one or more <note> tags.
>
> Why so complicated? Can you give a *reasonable* example of the intended usage 
> of this feature?

Yes. User notes on a website. 
This website has been in the pipeline for a long time.

>
>> They are typeset as an unordered list, which means that it can basically 
>> contain the same things as a <li> element.
>> (so no tables, code blocks and what not).
>> 
>> By default, the <notes> tag is ignored.
>> 
>> Only if you give fpdoc the --emit-notes option, then the notes will be 
>> included in the output.
>> (at least in HTML and all linear output).
>
> It looks to me as if you only implemented only half of a possibly much more 
> powerful feature. Provided that your intention is about *conditional* parts, 
> which are formatted for inclusion into the final docs, I'm missing more 
> detailed condition handling. Then it would be possible to e.g. provide 
> documention specific to a platform or widgetset, wherever different 
> implementations or behaviour suggest such separate documentation.
>
> Apart from that, author/editor notes deserve no special structure or 
> formatting, and should be easier to insert (what about LazDE?).
>
> What about a less structured solution, e.g.
>  <notes XYZ deserves a clarification!/>
> for an alternative use of the just introduced tag?

You must be joking ?

Let me recapitulate.

1. You were complaining that you cannot enter notes.

2. You make do with [note whatever] in current lazarus docs.

3. People seem to agree some kind of note functionality is in order.

4. Noting all this, I can see the use of author's notes, and decide to add
    a feature for notes, which is extensible if need be, and can be added to
    any editor with a minimum of effort, making them easy to manage.
    As a bonus, they come in handy for a  long-standing idea, namely,
    a collaborative website for creating docs.

And now you have the incredible nerve to complain that

a) it is "too complicated"

b) "notes deserve no structure or formatting"

c) it "misses features for conditionals" in a "more powerful solution"

Disregarding the fact that I think your complaints are simply contradicting 
each other I am simply *apalled* at the fact you have the guts to complain.

Michael.