[Issue 10236] Ddoc: Warning on wrong parameter names

[d-bugmail at puremagic.com]

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



--- Comment #7 from bearophile_hugs at 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: -------