www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 4520] New: add support for //! style documentation comments

reply d-bugmail puremagic.com writes:
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



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: -------
Jul 27 2010
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520


bearophile_hugs eml.cc changed:

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



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: -------
Jul 27 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520




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: -------
Jul 27 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520


Leandro Lucarella <llucax gmail.com> changed:

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



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: -------
Jul 27 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520


Jonathan M Davis <jmdavisProg gmail.com> changed:

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



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: -------
Jul 27 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520




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: -------
Jul 27 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=4520




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: -------
Jul 28 2010
prev sibling parent d-bugmail puremagic.com writes:
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



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: -------
Feb 05 2012