http://d.puremagic.com/issues/show_bug.cgi?id=4520

           Summary: add support for //! style documentation comments
           Product: D
           Version: D1 & D2
          Platform: All
        OS/Version: All
            Status: NEW
          Keywords: ddoc, patch
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: nobody@puremagic.com
        ReportedBy: mrmocool@gmx.de


--- Comment #0 from Trass3r <mrmocool@gmx.de> 2010-07-27 10:28:43 PDT ---
Created an attachment (id=699)
patch for the lexer

I added //! style documentation comments to my dmd and thought I'd share that.

Since it only requires minimal changes to the lexer and doesn't add any complexity to the compiler it could be integrated into dmd.

Note: Doxygen supports these comments.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520


bearophile_hugs@eml.cc changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bearophile_hugs@eml.cc


--- Comment #1 from bearophile_hugs@eml.cc 2010-07-27 11:08:37 PDT ---
What's the advantage of using //! instead of the /// style that is already supported?

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520



--- Comment #2 from Trass3r <mrmocool@gmx.de> 2010-07-27 11:13:46 PDT ---
Well it's personal taste.
As I said, only requires minimal changes to the lexer, Doxygen also uses ///
and //!, so why not? It's just a proposal.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520


Leandro Lucarella <llucax@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |llucax@gmail.com


--- Comment #3 from Leandro Lucarella <llucax@gmail.com> 2010-07-27 13:59:21 PDT ---
The fact that is used often in Doxygen might be a factor to include this patch, since it will make life easier for people used to use Doxygen.

Is not a very strong argument for including it, though :)

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520


Jonathan M Davis <jmdavisProg@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jmdavisProg@gmail.com


--- Comment #4 from Jonathan M Davis <jmdavisProg@gmail.com> 2010-07-27 14:54:00 PDT ---
Except that /// and /** */ are already supported in D and used by doxygen. So, if you're looking for doxygen support, we already have it. It's true that //! is another way to do comments that doxygen supports, but it's not necessary.

Also, what exactly is this patch supposed to do? Does it make it so that //! are treated like ddoc comments? Because //! is already a perfectly legitimate comment because it starts with //, and doxygen will read it exactly the same way it reads ///. If it is the case that it's ddoc comments that you're looking for, I'd argue that you should actually use /++ +/ rather than a doxygen style since doxygen comments are done differently than ddoc comments anyway (doxygen favoring tags and ddoc comments being freeform).

Regardless, I don't care one way or another whether this patch gets included. I just don't see the point.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520



--- Comment #5 from Trass3r <mrmocool@gmx.de> 2010-07-27 15:14:14 PDT ---
The patch makes //! treated as a ddoc comment.
As I already said, it's just a matter of taste. I prefer //! so I patched my
dmd to be free to choose.

I didn't claim this was necessary in any way (which is why this is marked as ENHANCEMENT). It's a tiny 3-line patch that doesn't hurt so I added it here.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520



--- Comment #6 from Sobirari Muhomori <dfj1esp02@sneakemail.com> 2010-07-28 11:24:39 PDT ---
I'm afraid, it's useless. Doxygen uses its own markup and macros, they will be treated as plain text in ddoc comments. It's useless.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=4520


Yao Gomez <yao.gomez@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |yao.gomez@gmail.com
         Resolution|                            |WONTFIX


--- Comment #7 from Yao Gomez <yao.gomez@gmail.com> 2012-02-05 14:31:20 PST ---
There was recently a pull request to add this type of doc comments to DMD (I think that it was Trass3r too the one doing it) and it was rejected and closed by Walter & Co.

So I think that it's pretty safe to assume that this definitely will not be accepted. So with this in mind I'm closing this bug report.

However, if you want to give the good fight and make another attempt, please reopen and add your comments.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------