www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 9676] New: Html doc generation with <del>...</del> around deprecated functions names

reply d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676

           Summary: Html doc generation with <del>...</del> around
                    deprecated functions names
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: nobody puremagic.com
        ReportedBy: bearophile_hugs eml.cc


--- Comment #0 from bearophile_hugs eml.cc 2013-03-09 08:58:42 PST ---
A low priority enhancement request.

This D code:


module test;
///
deprecated void foo() {}
void main() {}



Compiled with doc generation (-D) gives the HTML:



<html><head>
        <META http-equiv="content-type" content="text/html; charset=utf-8">
        <title>test</title>
        </head><body>
        <h1>test</h1>
        <!-- Generated by Ddoc from temp.d -->
<br><br>
<dl><dt><big><a name="foo"></a>deprecated void <u>foo</u>();
</big></dt>
<dd><br><br>
</dd>
</dl>
<hr><small>Page generated by <a href="http://dlang.org/ddoc.html">Ddoc</a>.
</small>
</body></html>



I suggest to add <del>...</del> pairs around the name of deprecated functions:

<dl><dt><big><a name="foo"></a>deprecated <del>void <u>myfunc</u>();</del>

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 09 2013
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |andrej.mitrovich gmail.com
         AssignedTo|nobody puremagic.com        |andrej.mitrovich gmail.com
            Summary|Html doc generation with    |Deprecated declarations
                   |<del>...</del> around       |should be wrapped in a
                   |deprecated functions names  |$(DEP) macro


--- Comment #1 from Andrej Mitrovic <andrej.mitrovich gmail.com> 2013-03-11
17:27:23 PDT ---
HTML hardcoding is unnecessary. Instead we should introduce a $(DEP) macro,
which can expand to the supported export format.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 11 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |pull


--- Comment #2 from Andrej Mitrovic <andrej.mitrovich gmail.com> 2013-03-11
17:32:43 PDT ---
https://github.com/D-Programming-Language/dmd/pull/1740

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 11 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #3 from bearophile_hugs eml.cc 2013-03-12 17:42:21 PDT ---
Andrej Mitrovic:

I thought bearophile just wanted the ability to highlight the function in some
way to make it stand-out more.<

I wanted dmd to add <del></del> around the function, to make it stand-oud less than other functions (to make it more visually clear they are deprecated). Walter:
Yes, it should wrap the whole thing. Then bearophile can add his own definition
of DEP to highlight as he wishes with it.<

This issue asks for <del></del> in the standard online documentation. I don't have personal uses for such a macro. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 12 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #4 from bearophile_hugs eml.cc 2013-03-12 17:48:06 PDT ---
Walter:

the default expansion for deprecated symbols should be to nothing. Otherwise,
people will continue to use them.<

I think this isn't a good idea. If I am using a function in my code and it's deprecated this forces me to go read the source code. If you don't want a function to be visible in the documentation then replace its /**...*/ and /// with /*...*/ and //. In Scala deprecated names are clearly visible as deprecated, but they aren't invisible, I think this is the right default: http://twitter.github.com/algebird/com/twitter/algebird/BloomFilterMonoid.html -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 12 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #5 from Andrej Mitrovic <andrej.mitrovich gmail.com> 2013-03-12
17:49:58 PDT ---
(In reply to comment #3)
 This issue asks for <del></del> in the standard online documentation. I don't
 have personal uses for such a macro.

Right, but you can't add <del></del> without knowing where to inject it to, hence why you need a macro first. Then for HTML generation $(DEPRECATED foo) will simply expand to <del>foo</del>. So essentially these are two feature requests, one depends on the other. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 12 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #6 from Andrej Mitrovic <andrej.mitrovich gmail.com> 2013-03-12
17:51:28 PDT ---
(In reply to comment #5)
 So essentially these are two feature requests, one depends on the other.

Although perhaps I should have opened a separate issue instead of hijacking your ER. Sorry about that! -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 12 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #7 from bearophile_hugs eml.cc 2013-03-12 18:36:14 PDT ---
(In reply to comment #5)

 Right, but you can't add <del></del> without knowing where to inject it to,
 hence why you need a macro first.

I am aware of this. (In reply to comment #6)
 Although perhaps I should have opened a separate issue instead of hijacking
 your ER. Sorry about that!

Don't worry, small misunderstandings between persons are common. And I think the two issues are closely related. -- Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email ------- You are receiving this mail because: -------
Mar 12 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676


Walter Bright <bugzilla digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bugzilla digitalmars.com


--- Comment #8 from Walter Bright <bugzilla digitalmars.com> 2013-03-15
13:52:15 PDT ---
https://github.com/D-Programming-Language/dmd/pull/1740

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 15 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676



--- Comment #9 from github-bugzilla puremagic.com 2013-03-15 13:52:58 PDT ---
Commits pushed to master at https://github.com/D-Programming-Language/dmd

https://github.com/D-Programming-Language/dmd/commit/3713141018e8c919288de10ab357333c5e93afc3
Fixes Issue 9676 - Deprecated declarations should be wrapped in
$(DEPRECATED) macro.

https://github.com/D-Programming-Language/dmd/commit/69717dc210a1adde1e2dd8026143b64aa8c85119
Merge pull request #1740 from AndrejMitrovic/Fix9676

Issue 9676 - Deprecated declarations should be wrapped in $(DEPRECATED) macro.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 15 2013
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9676


Walter Bright <bugzilla digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED
            Summary|Deprecated declarations     |Ddoc: Wrap deprecated
                   |should be wrapped in a      |declarations in a
                   |$(DEPRECATED) macro         |$(DEPRECATED) macro


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