Re: [Dtddoc-develop] Correct form of doc comments?

[Stefan C. <sch...@sk...>]

Le 16-juil.-06 =E0 12:50, Herv=E9 BOUTEMY a =E9crit :

> Hi Andrew,
>
> I personnaly don't know af another tool named DTDDoc.

There are some, just google.

>
> I had a look at CVS's history : it was so at the initial revision, =20
> on May 25
> 2002 :

Damn it's already 4 years old !

>
> I think the idea was that even before DTDDoc existed, people were =20
> smart enough
> to comment their DTDs : raw information was here, waiting for =20
> DTDDoc to
> publish it ! :)

So I conclude I was a smart guy :)

> That's only later that @xxx conventions "=E0 la javadoc" were added : =20=

> asking for
> an extra "-" like the extra "*" from javadoc would have lead to =20
> loose all
> these free comments.

Not sure I get it.

>
> To me, "<!---" is a bug in Netbeans.

I'd say a design decision.

> Now, if you think it would be useful to distinguish normal DTD =20
> comment from
> DTDDoc comments (just like javadoc doesn't render basic comments), =20
> perhaps we
> can add it to DTDDoc's feature list, as an Ant task option (name to =20=

> find : if
> you have an idea of a meaningful name...).

I definitely consider this suggestion worth the effort.

>
> Herv=E9
>
> Le Vendredi 14 Juillet 2006 11:56, Andrew Stevens a =E9crit :
>> I stumbled across DTDDoc because a DTD I generated in Netbeans =20
>> (from an
>> existing XML document) contained a whole load of comments which read
>> <!--- Put your DTDDoc comment here. -->
>> by each element or attribute declaration.  Nice tool :-)
>>
>> However, I noticed that the generated docs all have a leading "-", =20=

>> which I
>> assume is because the comments Netbeans generated use "<!---" (in =20
>> the same
>> way that javadoc comments use "/**" rather than just "/*") and =20
>> DTDDoc is
>> expecting just "<!--".  So I'm wondering whether this has always =20
>> been the
>> case, or the Netbeans module is simply doing it wrong, or if I've =20
>> found the
>> wrong tool and there's another DTDDoc that expects the other form?
>>
>>
>> Andrew.