I'm putting the finishing touches on my syntax coloring for VS.NET, and thought providing a few options for comments might be nice. For instance, since I was already lexing them, I defined a new color class for D's nesting comments, /+ +/, so that sections of code in those comments can be a different color.

In looking through the Phobos source code, I found some examples of comments that might be intended for documentation extracting tools. For instance, in recl.d, Matthew has used notations that are obviously documentation for an external tool, such as:

/// Advances the given search to the next position
///
/// \param hSrch handle identifying the search
/// \return return code indicating status of the operation
/// \return RECLS_

In the C# editor in VS.NET, Microsoft recognizes comment lines beginning with three slashs, as above, as doucmentation comments, and they can be colored differently than normal comments, but they use XML for the comment tags. I like this, although I would fix it so that a line consisting only of slashes (a heading or separator line) would not be colored.

Anyway, I was wondering if there are any commonly used documentation tool(s), and if they have a specific comment format that can be colored uniquely. I don't recall reading that D has any predefined comment conventions for such purposes. And also, whether this is even desirable (although you could always set all comment styles to the same color if you didn't want it).

Any feedback welcome...

-- 
dave

Dave Sieber wrote:

> I'm putting the finishing touches on my syntax coloring for VS.NET, and thought providing a few options for comments might be nice. For instance, since I was already lexing them, I defined a new color class for D's nesting comments, /+ +/, so that sections of code in those comments can be a different color.
> 
> In looking through the Phobos source code, I found some examples of comments that might be intended for documentation extracting tools. For instance, in recl.d, Matthew has used notations that are obviously documentation for an external tool, such as:
> 
> /// Advances the given search to the next position
> ///
> /// \param hSrch handle identifying the search
> /// \return return code indicating status of the operation
> /// \return RECLS_
> 
> In the C# editor in VS.NET, Microsoft recognizes comment lines beginning with three slashs, as above, as doucmentation comments, and they can be colored differently than normal comments, but they use XML for the comment tags. I like this, although I would fix it so that a line consisting only of slashes (a heading or separator line) would not be colored.
> 
> Anyway, I was wondering if there are any commonly used documentation tool(s), and if they have a specific comment format that can be colored uniquely. I don't recall reading that D has any predefined comment conventions for such purposes. And also, whether this is even desirable (although you could always set all comment styles to the same color if you didn't want it).

I believe that the format used by Matthew above is recognized by Doxygen, a documentation tool widely used in the Open Source community.
D filters for doxygen exists (search for Doxygen in the newsgroup), but
I don't know if the support is included (or will be) in the main
distribution of Doxygen.

Lars Ivar Igesund

Lars Ivar Igesund <larsivar@igesund.net> wrote:

> I believe that the format used by Matthew above is recognized by Doxygen, a documentation tool widely used in the Open Source community. D filters for doxygen exists (search for Doxygen in the newsgroup), but I don't know if the support is included (or will be) in the main distribution of Doxygen.

Thanks, that's just what I was looking to find out. At this point I only want to know the comment styles (such as leading "///") in order to syntax color them, and will consult the Doxygen documentation to see what they use.


-- 
dave

In asking about your D grammar in another post, I was asking because I wanted to do a source-code formatter.  And then, "while I was there" so to speak, with the lexer results, I was going to write a tool similar to javadoc.  This was all going to be academic for me to learn D, but the more I think about it, going with doxygen makes more sense.  Plus I have my hands full with dsource and work.

BA

Dave Sieber wrote:
> I'm putting the finishing touches on my syntax coloring for VS.NET, and thought providing a few options for comments might be nice. For instance, since I was already lexing them, I defined a new color class for D's nesting comments, /+ +/, so that sections of code in those comments can be a different color.
> 
> In looking through the Phobos source code, I found some examples of comments that might be intended for documentation extracting tools. For instance, in recl.d, Matthew has used notations that are obviously documentation for an external tool, such as:
> 
> /// Advances the given search to the next position
> ///
> /// \param hSrch handle identifying the search
> /// \return return code indicating status of the operation
> /// \return RECLS_
> 
> In the C# editor in VS.NET, Microsoft recognizes comment lines beginning with three slashs, as above, as doucmentation comments, and they can be colored differently than normal comments, but they use XML for the comment tags. I like this, although I would fix it so that a line consisting only of slashes (a heading or separator line) would not be colored.
> 
> Anyway, I was wondering if there are any commonly used documentation tool(s), and if they have a specific comment format that can be colored uniquely. I don't recall reading that D has any predefined comment conventions for such purposes. And also, whether this is even desirable (although you could always set all comment styles to the same color if you didn't want it).
> 
> Any feedback welcome...
> 

Brad Anderson <brad@dsource.dot.org> wrote:

> In asking about your D grammar in another post, I was asking because I
> wanted to do a source-code formatter.  And then, "while I was there"
> so to speak, with the lexer results, I was going to write a tool
> similar to javadoc.  This was all going to be academic for me to learn
> D, but the more I think about it, going with doxygen makes more sense.
>  Plus I have my hands full with dsource and work.

A source code formatter is a very good idea, especially if it can really reformat (rather than just reindent).  I'd suggest looking into ANTLR for that, as it looks like something it would be good at. Of course, a grammar would still have to be developed. Above and beyond that, I think a refactoring tool would be awesome, or even just a smarter editor that understood code. These are all things I am interested in.

Doxygen looks nice. I was checking it out this morning to add a new color class for Doxygen comments to my syntax highlighter (although they have a few too many ways to write the comments :-). In the past, I've found that using Javadoc was the only thing I would really stick with, so maybe I should look into Doxygen for documenting D code.

-- 
dave

"Dave Sieber" <dsieber@spamnot.sbcglobal.net> wrote in message news:Xns94CBA4BF1CD07dsiebersbc@63.105.9.61...
> Brad Anderson <brad@dsource.dot.org> wrote:
>
> > In asking about your D grammar in another post, I was asking because I
> > wanted to do a source-code formatter.  And then, "while I was there"
> > so to speak, with the lexer results, I was going to write a tool
> > similar to javadoc.  This was all going to be academic for me to learn
> > D, but the more I think about it, going with doxygen makes more sense.
> >  Plus I have my hands full with dsource and work.
>
> A source code formatter is a very good idea, especially if it can really reformat (rather than just reindent).  I'd suggest looking into ANTLR for that, as it looks like something it would be good at. Of course, a grammar would still have to be developed. Above and beyond that, I think a refactoring tool would be awesome, or even just a smarter editor that understood code. These are all things I am interested in.

I nead D grammar too, and i'am sure there are people out there who
are good at writing gramars so i say PLEASE to that somebody to write a D
grammar and make it available to us :)

"Ivan Senji" <ivan.senji@public.srce.hr> wrote:

> I nead D grammar too, and i'am sure there are people out there who are good at writing gramars so i say PLEASE to that somebody to write a D grammar and make it available to us :)

I'm curious: what use would you have for a D grammar? And what kind of grammar do you need/want (yacc, ANTLR, other)? Is there some special D tool you want to write?

In my case, using Babel for language support in Visual Studio, a Yacc grammar would be nice to have, because Babel works with Lex and Yacc. But for anything else, I would try to not use Yacc.

-- 
dave

"Dave Sieber" <dsieber@spamnot.sbcglobal.net> wrote in message news:Xns94CC268C12080dsiebersbc@63.105.9.61...
> "Ivan Senji" <ivan.senji@public.srce.hr> wrote:
>
> > I nead D grammar too, and i'am sure there are people out there who are good at writing gramars so i say PLEASE to that somebody to write a D grammar and make it available to us :)
>
> I'm curious: what use would you have for a D grammar? And what kind of grammar do you need/want (yacc, ANTLR, other)? Is there some special D
tool
> you want to write?

I have writen an LR(1) parser (in D) and i would like to test it with
Dgrammar.
So i need LR(1) or a little worse grammar (it can be a little worse because
my parser is nondeterministic). What tool? No idea yet. But when i think of
a way to generate some output who knows :)

> In my case, using Babel for language support in Visual Studio, a Yacc grammar would be nice to have, because Babel works with Lex and Yacc. But for anything else, I would try to not use Yacc.

Can't wait to see this support, are yout using some grammar for this?

> --
> dave

"Dave Sieber" <dsieber@spamnot.sbcglobal.net> wrote in message news:Xns94CC268C12080dsiebersbc@63.105.9.61...
> "Ivan Senji" <ivan.senji@public.srce.hr> wrote:
>
> > I nead D grammar too, and i'am sure there are people out there who are good at writing gramars so i say PLEASE to that somebody to write a D grammar and make it available to us :)
>
> I'm curious: what use would you have for a D grammar? And what kind of grammar do you need/want (yacc, ANTLR, other)? Is there some special D
tool
> you want to write?

I have writen an LR(1) parser (in D) and i would like to test it with
Dgrammar.
So i need LR(1) or a little worse grammar (it can be a little worse because
my parser is nondeterministic). What tool? No idea yet. But when i think of
a way to generate some output who knows :)

> In my case, using Babel for language support in Visual Studio, a Yacc grammar would be nice to have, because Babel works with Lex and Yacc. But for anything else, I would try to not use Yacc.

Can't wait to see this support, are yout using some grammar for this?

> --
> dave

"Ivan Senji" <ivan.senji@public.srce.hr> wrote:

> I have writen an LR(1) parser (in D) and i would like to test it with
> Dgrammar.
> So i need LR(1) or a little worse grammar (it can be a little worse
> because my parser is nondeterministic). What tool? No idea yet. But
> when i think of a way to generate some output who knows :)

Sounds fascinating!

> Can't wait to see this support, are yout using some grammar for this?

I'm now evaluating the decision to continue with yacc (and write a complete D grammar myself), or to use Walter's front-end code and adapt it to Visual Studio's extensibiity model.

I think I will stay with the Flex lexer I wrote, because it is working very well now for syntax coloring, and I've defined custom color classes for all the integral types (decimal, octal, hex, binary), floats and imaginaries, strings (regular and wysisyg), and several comment styles (/* normal */, /+ D nesting style +/ , and a few Doxygen styles).

-- 
dave