On Wednesday, 18 March 2015 at 19:28:44 UTC, Jacob Carlborg wrote:
> On 2015-03-18 19:48, Walter Bright wrote:
>> I'm fed up with this problem. It is actively hurting us every day.
>>
>> https://issues.dlang.org/show_bug.cgi?id=14307
>>
>> Anyone want to take this on? Shouldn't be particularly difficult.
>
> I'm not so sure about this. I think there's a big chance that users will just add an empty documentation comment to silence the error.
>

It is not a good chance, it is 100% guaranteed.

And I'm sorry, but if most function require DDoc, your code probably sucks quite badly and some renaming should be considered.

On Wednesday, 18 March 2015 at 19:43:47 UTC, Andrei Alexandrescu wrote:
> On 3/18/15 12:28 PM, Jacob Carlborg wrote:
>> On 2015-03-18 19:48, Walter Bright wrote:
>>> I'm fed up with this problem. It is actively hurting us every day.
>>>
>>> https://issues.dlang.org/show_bug.cgi?id=14307
>>>
>>> Anyone want to take this on? Shouldn't be particularly difficult.
>>
>> I'm not so sure about this. I think there's a big chance that users will
>> just add an empty documentation comment to silence the error.
>
> That won't pass review. -- Andrei

Here is what will pass review :

class User {
   /**
    * Accessor to get the id of the user.
    *
    * @return : the id of the user
    */
   uint getUserID() { ... }

   /**
    * Accessor to get the name of the user.
    *
    * @return : the name of the user
    */
   string getName() { ... }

// ...
}

This is very popular in "enterprise" code, and there is a reason everybody hates it.

On Wednesday, 18 March 2015 at 22:05:18 UTC, Brian Schott wrote:
> On Wednesday, 18 March 2015 at 18:48:53 UTC, Walter Bright wrote:
>> I'm fed up with this problem. It is actively hurting us every day.
>>
>> https://issues.dlang.org/show_bug.cgi?id=14307
>>
>> Anyone want to take this on? Shouldn't be particularly difficult.
>
> D-Scanner has had this feature for a while. Here's the list for Phobos:
>
> http://dpaste.dzfl.pl/7d018aad2b10

That's a very interesting list. Things like this:

std/regex/package.d(320:13)[warn]: Public declaration 'regexImpl' is undocumented.

appear to be public only as an workaround (necessary for mixins or something). Perhaps such things shouldn't actually be documented. But we don't have a mechanism for that.

On Wednesday, 18 March 2015 at 18:48:53 UTC, Walter Bright wrote:
> I'm fed up with this problem. It is actively hurting us every day.
>
> https://issues.dlang.org/show_bug.cgi?id=14307
>
> Anyone want to take this on? Shouldn't be particularly difficult.

This is going to be a lot of fun as soon as tons of currently private functions in phobos are public due to the usage of "export".

On Wednesday, 18 March 2015 at 18:48:53 UTC, Walter Bright wrote:
> I'm fed up with this problem. It is actively hurting us every day.
>
> https://issues.dlang.org/show_bug.cgi?id=14307
>
> Anyone want to take this on? Shouldn't be particularly difficult.

I would like this but issue warnings not errors. I like every function to be documented. Also don't make the Example mandatory because people tend to use unittest blocks as the examples.

On Thursday, 19 March 2015 at 11:27:20 UTC, Gary Willoughby wrote:
> I would like this but issue warnings not errors. I like every function to be documented. Also don't make the Example mandatory because people tend to use unittest blocks as the examples.

Why not just make unittests mandatory, and completely forego the
examples?

On Wednesday, 18 March 2015 at 18:48:53 UTC, Walter Bright wrote:
> I'm fed up with this problem. It is actively hurting us every day.
>
> https://issues.dlang.org/show_bug.cgi?id=14307
>
> Anyone want to take this on? Shouldn't be particularly difficult.

I think this is a good idea. Even the most trivial looking function might not be so trivial looking to consumers of the API. Document everything. If you can't explain a function in a public API (where protected is also public), then why should it exist?

On Thursday, 19 March 2015 at 09:43:35 UTC, deadalnix wrote:
> This is very popular in "enterprise" code, and there is a reason everybody hates it.

Garbage like this is why Harbored treats the "Returns:" section as the summary when the summary is missing.

It's also the reason that D-Scanner's undocumented declaration check skips functions whose name starts with "get" or "set".

On 3/19/2015 3:02 AM, Don wrote:
> appear to be public only as an workaround (necessary for mixins or something).
> Perhaps such things shouldn't actually be documented. But we don't have a
> mechanism for that.

We already have a special:

    /// ditto

comment. Perhaps:

    /// undocumented

? At least then it would be a deliberate choice.

On 3/19/2015 2:43 AM, deadalnix wrote:
> Here is what will pass review :

Presumably the reviewers will have some common sense and taste.

> class User {
>     /**
>      * Accessor to get the id of the user.
>      *
>      * @return : the id of the user
>      */
>     uint getUserID() { ... }
>
>     /**
>      * Accessor to get the name of the user.
>      *
>      * @return : the name of the user
>      */
>     string getName() { ... }

Accessor functions that merely return a field variable are bull anyway.


> This is very popular in "enterprise" code, and there is a reason everybody hates
> it.

I think the problem is more with the desire to have noise wrappers like:

    int foo;
    int getFoo() { return foo; }