www.digitalmars.com         C & C++   DMDScript  

D - Regarding comments

reply Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
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
Apr 13 2004
next sibling parent reply Lars Ivar Igesund <larsivar igesund.net> writes:
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
Apr 13 2004
parent Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
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
Apr 13 2004
prev sibling parent reply Brad Anderson <brad dsource.dot.org> writes:
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...
 

Apr 14 2004
parent reply Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
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
Apr 14 2004
parent reply "Ivan Senji" <ivan.senji public.srce.hr> writes:
"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 :)
Apr 14 2004
parent reply Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
"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
Apr 15 2004
next sibling parent "Ivan Senji" <ivan.senji public.srce.hr> writes:
"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

 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

Apr 15 2004
prev sibling parent reply "Ivan Senji" <ivan.senji public.srce.hr> writes:
"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

 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

Apr 15 2004
parent reply Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
"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
Apr 15 2004
parent reply C <dont respond.com> writes:
 I'm now evaluating the decision to continue with yacc (and write a =

 complete
 D grammar myself)

I hope you go with this, a yacc grammar would be awesome, but I think D = wont fit into LL(1) parsers ? Either way a d-parser of some sort would = be = a great tool for alot of people. Good luck! C On Thu, 15 Apr 2004 15:42:49 +0000 (UTC), Dave Sieber = <dsieber spamnot.sbcglobal.net> wrote:
 "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 fo=

 all
 the integral types (decimal, octal, hex, binary), floats and imaginari=

 strings (regular and wysisyg), and several comment styles (/* normal *=

 /+
 D nesting style +/ , and a few Doxygen styles).

-- = D Newsgroup.
Apr 15 2004
parent reply Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
C <dont respond.com> wrote:

 I hope you go with this, a yacc grammar would be awesome, but I think
 D wont fit into LL(1) parsers ?  Either way a d-parser of some sort
 would be a great tool for alot of people.

I agree that a grammar would be valuable, but I'm also looking at my goal, which is full Intellisense and Class View support for D in Visual Studio. For it to be as good as I desire, it must be as correct as possible -- something which Microsoft themselves have not achieved with their C++ support in VS.NET. Luckily, D is simpler than C++, but when I talked with the Visual C++ team in Redmond, I learned that they were not using the same C++ parser in VS.NET as in the compiler (oops!), and thus while the compiler got everything right, VS.NET did not. I definitely do not want to repeat that mistake with D (easier said than done. The MS crew were all very smart guys, but we're simply talking about two different requirement sets: a compiler vs. a syntax-directed editor). I look at what Walter has in the front-end code, and it is much better than a parser I could write myself from scratch, and it's already done. With a yacc grammar, because of its limitations, you usually have to make it dumber than you would like, and use semantic analysis to get things right. Walter has already done all that. I'd be reinventing the wheel, and I doubt I understand the language as well as he does. My only real hesitation is that it would take a lot of tweaking to adapt Walter's code for Visual Studio (which I'm willing to do), but when he comes out with a new version, or maybe adds some new features, I'd have to go back and re-tweak his code again :-( Of course, I'd have to do that with a yacc grammar too.
 Good luck!

Thanks, I'll need it :-) -- dave
Apr 15 2004
parent reply "Walter" <walter digitalmars.com> writes:
"Dave Sieber" <dsieber spamnot.sbcglobal.net> wrote in message
news:Xns94CC668C5785Fdsiebersbc 63.105.9.61...
 I agree that a grammar would be valuable, but I'm also looking at my goal,
 which is full Intellisense and Class View support for D in Visual Studio.
 For it to be as good as I desire, it must be as correct as possible -- 
 something which Microsoft themselves have not achieved with their C++
 support in VS.NET. Luckily, D is simpler than C++, but when I talked with
 the Visual C++ team in Redmond, I learned that they were not using the

 C++ parser in VS.NET as in the compiler (oops!), and thus while the
 compiler got everything right, VS.NET did not. I definitely do not want to
 repeat that mistake with D (easier said than done. The MS crew were all
 very smart guys, but we're simply talking about two different requirement
 sets: a compiler vs. a syntax-directed editor).

With D, I wanted to make it easy to make tools for D that needed a parser, so the language is designed to be easy to parse. The entire parser is contained in parse.h/parse.c. The entire lexer is in lexer.h/lexer.c. Parsing C++ is fiendishly complicated, and doing it 100% correct requires building most of a C++ front end, a 10 year task. A major design goal of D is to avoid that problem.
 I look at what Walter has in the front-end code, and it is much better

 a parser I could write myself from scratch, and it's already done. With a
 yacc grammar, because of its limitations, you usually have to make it
 dumber than you would like, and use semantic analysis to get things right.
 Walter has already done all that. I'd be reinventing the wheel, and I

 I understand the language as well as he does.

I think as much as possible adapting parse.h/parse.c will get you better results.
 My only real hesitation is that it would take a lot of tweaking to adapt
 Walter's code for Visual Studio (which I'm willing to do), but when he
 comes out with a new version, or maybe adds some new features, I'd have to
 go back and re-tweak his code again :-(  Of course, I'd have to do that
 with a yacc grammar too.

I doubt any big changes to the grammar are coming, so any changes that do come should be easy to fold in if you keep the parse.c you started with, and diff the new one against it to see what changed.
Apr 15 2004
parent Dave Sieber <dsieber spamnot.sbcglobal.net> writes:
"Walter" <walter digitalmars.com> wrote:

 I doubt any big changes to the grammar are coming, so any changes that
 do come should be easy to fold in if you keep the parse.c you started
 with, and diff the new one against it to see what changed.

Thanks for the reassuring answers, Walter. I think that helps me make up my mind :-) -- dave
Apr 15 2004