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

[Andrew S. <at...@ho...>]

>From: Hervé BOUTEMY <her...@fr...>
>Date: Sun, 16 Jul 2006 12:50:46 +0200
>
>Hi Andrew,
>
>I personnaly don't know af another tool named DTDDoc.
>
>I had a look at CVS's history : it was so at the initial revision, on May 
>25
>2002 :
>http://dtddoc.cvs.sourceforge.net/dtddoc/DTDDoc/example/common_figure.dtd?hideattic=0&revision=1.1&view=markup
>
>I think the idea was that even before DTDDoc existed, people were smart 
>enough
>to comment their DTDs : raw information was here, waiting for DTDDoc to
>publish it ! :)
>That's only later that @xxx conventions "à la javadoc" were added : asking 
>for
>an extra "-" like the extra "*" from javadoc would have lead to loose all
>these free comments.
>
>To me, "<!---" is a bug in Netbeans.
>Now, if you think it would be useful to distinguish normal DTD comment from
>DTDDoc comments (just like javadoc doesn't render basic comments), perhaps 
>we
>can add it to DTDDoc's feature list, as an Ant task option

Whatever you think best, I guess.  I didn't find it unexpected for the doc 
comments to be different to the ordinary ones since that's what I was used 
to from javadoc.  On the other hand, if you don't want to change it I can 
just as easily raise a bug report with Netbeans.

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

Hmm...  docCommentDelimiters="true", perhaps?


Andrew.

>
>Hervé
>
>Le Vendredi 14 Juillet 2006 11:56, Andrew Stevens a écrit :
> > I stumbled across DTDDoc because a DTD I generated in Netbeans (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 "-", which 
>I
> > assume is because the comments Netbeans generated use "<!---" (in the 
>same
> > way that javadoc comments use "/**" rather than just "/*") and DTDDoc is
> > expecting just "<!--".  So I'm wondering whether this has always been 
>the
> > case, or the Netbeans module is simply doing it wrong, or if I've found 
>the
> > wrong tool and there's another DTDDoc that expects the other form?
> >
> >
> > Andrew.