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

           Summary: Ddoc: Warning on wrong parameter names
           Product: D
           Version: unspecified
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: nobody@puremagic.com
        ReportedBy: lio+bugzilla@lunesu.com


--- Comment #0 from Lionello Lunesu <lio+bugzilla@lunesu.com> 2013-06-01 21:40:51 PDT ---
Ddoc does not complain when the parameters from "Params:" mismatch the actual parameters used in the function declaration.

I have a patch that issues as warning in such case. An additional case would be issuing a warning for missing parameters.

-- 
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=10236


bearophile_hugs@eml.cc changed:

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


--- Comment #1 from bearophile_hugs@eml.cc 2013-06-02 04:09:02 PDT ---
Such tests were discussed time ago, and to me they seem a good idea.

-- 
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=10236



--- Comment #2 from Lionello Lunesu <lio+bugzilla@lunesu.com> 2013-06-02 06:22:52 PDT ---
https://github.com/D-Programming-Language/dmd/pull/2121

Issues warnings for both the name and the count mismatch.

-- 
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=10236



--- Comment #3 from bearophile_hugs@eml.cc 2013-06-02 06:31:31 PDT ---
(In reply to comment #0)

> An additional case would be issuing a warning for missing parameters.

Another useful warning is when you document an argument that's not present in the argument list.

-- 
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=10236



--- Comment #4 from Lionello Lunesu <lio+bugzilla@lunesu.com> 2013-06-02 06:47:29 PDT ---
(In reply to comment #3)
> (In reply to comment #0)
> 
> > An additional case would be issuing a warning for missing parameters.
> 
> Another useful warning is when you document an argument that's not present in the argument list.

That's my first case: the parameters from "Params:" have to be present in the actual declaration. Next, I also check the parameter count.

-- 
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=10236


Walter Bright <bugzilla@digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |bugzilla@digitalmars.com
            Version|unspecified                 |D2


--- Comment #5 from Walter Bright <bugzilla@digitalmars.com> 2013-06-04 22:27:34 PDT ---
I have mixed feelings about this. Generally, Ddoc does not emit warnings or errors. This is deliberate, as it tries to interpret whatever random stuff the user may write as Ddoc stuff. If it isn't valid Ddoc, Ddoc shouldn't complain.

-- 
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=10236


lt.infiltrator@gmail.com changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |lt.infiltrator@gmail.com


--- Comment #6 from lt.infiltrator@gmail.com 2013-06-04 22:50:44 PDT ---
I get what you mean, Walter; but sometimes you'll make a change and forget to update the ddoc.  Perhaps making it complain by default isn't the correct way, and I know you hate the idea of adding more switches, but maybe have a --check-ddoc (or I guess with a single hash for dmd) for the ability to check your ddoc and say "hey, you forgot this; this doesn't match with your code; etc."

-- 
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=10236



--- Comment #7 from bearophile_hugs@eml.cc 2013-06-05 05:04:07 PDT ---
(In reply to comment #5)

> I have mixed feelings about this. Generally, Ddoc does not emit warnings or errors. This is deliberate, as it tries to interpret whatever random stuff the user may write as Ddoc stuff. If it isn't valid Ddoc, Ddoc shouldn't complain.

Languages as Python have more flexibility thanks to their dynamic typing. D has chosen to be a (mostly) statically typed language. So let's use such static typing (and Ahead Of Time compilation) for all it's able to give.

The tests proposed here are another excellent way to improve the D documentation using the capabilities D has, just like the documentation unittests.

Having documentation not in sync with the actual code is _worse_ than not having documentation. This enhancement request offers a chance to reduce such mistakes. Documentation bugs are bugs, because they are part of the API to interface a library with the brain of the humans that use it. Introducing quick compiler-enforced tests to reduce the amount of such mistakes is a good idea.

Instead of a warning I'd like this to become an error, eventually :-) If the programmer writes no documentation string, or he/she writes only a freestyle comment, no error is generated. If he/she chooses to use the ddoc syntax to list the arguments, that later the ddoc will pick to show them in a pretty formatted way, they must be correct.

It's common for comments to go out of sync with the code. Just like "static switch" this is an automatic help to keep different parts of the code in sync.

If you don't like this proposal, then please Walter write down a list of downsides and problems that this will cause. And let's see if each one of your points will hold.

-- 
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=10236



--- Comment #8 from Lionello Lunesu <lio+bugzilla@lunesu.com> 2013-06-05 19:49:54 PDT ---
(In reply to comment #5)
> I have mixed feelings about this. Generally, Ddoc does not emit warnings or errors. This is deliberate, as it tries to interpret whatever random stuff the user may write as Ddoc stuff. If it isn't valid Ddoc, Ddoc shouldn't complain.

In fact, Ddoc already has a couple of "warnings", that's why I stuck to warnings for this issue as well. You can't expect users to use Ddoc comments and then write non-Ddoc text. If that was the case, why do we have Ddoc comments to begin with?

-- 
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=10236



--- Comment #9 from Lionello Lunesu <lio+bugzilla@lunesu.com> 2013-08-25 09:08:16 PDT ---
Updated the pull request https://github.com/D-Programming-Language/dmd/pull/2121

FWIW, this patch has found numerous DDoc mistakes in phobos and druntime! I'd say that's proof enough.

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