www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Enhancement: issue error on all public functions that are missing

reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 18 2015
next sibling parent reply Jacob Carlborg <doob me.com> writes:
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.

I'm using a lint tool for Ruby that complains about this exact issue. 
Too often I just add an empty documentation comment do silence it. 
Although this mostly only happens for classes and modules, not for methods.

-- 
/Jacob Carlborg
Mar 18 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2015 12:28 PM, Jacob Carlborg wrote:

 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.


Right, but then it becomes glaringly obvious in the Pull Request and easier to 
reject.



 I'm using a lint tool for Ruby that complains about this exact issue. Too often
 I just add an empty documentation comment do silence it. Although this mostly
 only happens for classes and modules, not for methods.


Why use the tool if you're going to ignore it?

There are several features in D that are meant for QA use, and are not 
necessarily to make the programmer's life easier. This would be another of them.

It's clear we have an endemic problem in the Phobos documentation, and just 
exhorting people to do better is not working. The bar needs to be raised on
what 
is minimally acceptable.

Also, this feature would be enabled by a switch. Nobody has to use it, but I 
intend for it to be turned on for official D code.
Mar 18 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-03-18 20:37, Walter Bright wrote:


 Why use the tool if you're going to ignore it?


It's tremendously useful for reporting other issues. I can configure the 
tool to not report the this issue but sometimes it's just easier to ignore.

-- 
/Jacob Carlborg
Mar 18 2015
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Mar 18 2015
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2015-03-18 20:43, Andrei Alexandrescu wrote:


 That won't pass review. -- Andrei


If that's the case, how did an undocumented symbol pass review in the 
first place?

-- 
/Jacob Carlborg
Mar 19 2015
prev sibling parent reply "deadalnix" <deadalnix gmail.com> writes:
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.
Mar 19 2015
next sibling parent "Brian Schott" <briancschott gmail.com> writes:
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".
Mar 19 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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; }
Mar 19 2015
next sibling parent reply Jeremy Powers via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thu, Mar 19, 2015 at 3:03 PM, Walter Bright via Digitalmars-d <
digitalmars-d puremagic.com> wrote:

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


I would recommend against opening up this debate.  Suffice it to say that
this is a well established pattern that many people use; there is well-trod
ground arguing both sides.



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


A valid reason for doing things like this is future-proof encapsulation.
You can change the internal foo to be something entirely different, and the
external api never changes (assuming 'foo' is private).


As for the documentation - yeah, don't write docs that duplicate what is
there in the method signature.  In the above example, documentation should
explain what foo actually is, and why you might need it.  Otherwise is just
duplicate boilerplate that should be generated by the doc generator.
Mar 19 2015
next sibling parent reply "bachmeier" <no spam.net> writes:
On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:

 As for the documentation - yeah, don't write docs that 
 duplicate what is
 there in the method signature.


I'm not a big fan of that. It's one of those slippery slope 
things. The documentation should be written for a new D user, but 
the person that writes the method has a very different view of 
what constitutes duplication. There's too much of that attitude 
in the existing documentation. If it really is duplication, that 
should be a decision made by someone else, preferably someone 
that doesn't know much about the library.
Mar 19 2015
parent reply "deadalnix" <deadalnix gmail.com> writes:
On Thursday, 19 March 2015 at 23:45:03 UTC, bachmeier wrote:

 On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:

 As for the documentation - yeah, don't write docs that 
 duplicate what is
 there in the method signature.


 I'm not a big fan of that. It's one of those slippery slope 
 things. The documentation should be written for a new D user, 
 but the person that writes the method has a very different view 
 of what constitutes duplication. There's too much of that 
 attitude in the existing documentation. If it really is 
 duplication, that should be a decision made by someone else, 
 preferably someone that doesn't know much about the library.


Ok let's be clear. This kind of overpedantic commenting is a good 
thing in a public, widespread API, like phobos's. Especially 
since you can generate documentation from it, this is going to be 
googled for.

That is very bad idea in the general case.
Mar 19 2015
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 5:08 PM, deadalnix wrote:

 Ok let's be clear. This kind of overpedantic commenting is a good thing in a
 public, widespread API, like phobos's. Especially since you can generate
 documentation from it, this is going to be googled for.


Right, it's also to support automated tooling.
Mar 20 2015
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/20/15 4:26 PM, Walter Bright wrote:

 On 3/19/2015 5:08 PM, deadalnix wrote:

 Ok let's be clear. This kind of overpedantic commenting is a good
 thing in a
 public, widespread API, like phobos's. Especially since you can generate
 documentation from it, this is going to be googled for.


 Right, it's also to support automated tooling.


I also appreciate that whenever I go in some function like 
http://linux.die.net/man/3/popen I see the same uniform format. My 
purpose is not to write an exegesis of the documentation, but to just 
use the blessed function and be on my way.

I'd be super annoyed if whoever wrote the documentation chose to 
eliminate some sections for some functions just because <mock whiny 
voice>"they were a bit redundant"</mock whiny voice> or <mock whiny 
voice>"that's repetitive"</mock whiny voice>.


Andrei
Mar 20 2015
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/19/15 5:08 PM, deadalnix wrote:

 Ok let's be clear. This kind of overpedantic commenting is a good thing
 in a public, widespread API, like phobos's. Especially since you can
 generate documentation from it, this is going to be googled for.

 That is very bad idea in the general case.


Makes sense. -- Andrei
Mar 20 2015
prev sibling next sibling parent "Kagamin" <spam here.lot> writes:
On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote:

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


 A valid reason for doing things like this is future-proof 
 encapsulation.


That's a non-obvious property worth documenting. If it's a public 
API guaranteed to never change, that should be stated as such at 
least to warn against inconsiderate changes.
Mar 20 2015
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 3:13 PM, Jeremy Powers via Digitalmars-d wrote:

 A valid reason for doing things like this is future-proof encapsulation.  You
 can change the internal foo to be something entirely different, and the
external
 api never changes (assuming 'foo' is private).


That's why D has properties. Fields can be replaced with property functions.
Mar 20 2015
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 3/20/15 7:25 PM, Walter Bright wrote:

 On 3/19/2015 3:13 PM, Jeremy Powers via Digitalmars-d wrote:

 A valid reason for doing things like this is future-proof
 encapsulation.  You
 can change the internal foo to be something entirely different, and
 the external
 api never changes (assuming 'foo' is private).


 That's why D has properties. Fields can be replaced with property
 functions.


Replacing fields for properties and vice versa is an incompatible API 
change.

-Steve
Mar 23 2015
prev sibling next sibling parent reply "deadalnix" <deadalnix gmail.com> writes:
On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:

 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.


That is completely missing the point. If that is not clear enough 
:

/**
  * This class is the in program represention for a user.
  * It contains various user related data, and provides
  * various facilities for common user related operations.
  */
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 method will subscribe the user to the Subscribable
      * passed as argument.
      *
      * S: The Subscribable the user is going to subsribe to.
      *
      *  throw CantSubscribeException : In case the subscription 
fails,
      * an exception is thrown.
      */
     void subscribeUserTo(Subsribable S) { ... }

     /**
      * Send a message to the user. This can be used for 
commercial offers
      * or general information about the system.
      *
      * msg: The message you wish to send to the user.
      *
      *  throw MessageNotSentException : If for some reason, the 
message isn't
      * sent properly, a MessageNotSentException is sent.
      */
     sendMessage(string msg) { ... }

// And so on like forever...
}

Mandatory comment block is how you end up with overbloated code 
like this where it is explained to you 3 times in the comment 
what the method's name already tells you. And that is only the 
begging because starting from this point, overtime, comment 
become more and more out of date to ends up looking like an 
surrealistic form of humor.
Mar 19 2015
next sibling parent David Gileadi <gileadis NSPMgmail.com> writes:
On 3/19/15 3:26 PM, deadalnix wrote:

 On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:

 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.


 That is completely missing the point. If that is not clear enough :

 /**
   * This class is the in program represention for a user.
   * It contains various user related data, and provides
   * various facilities for common user related operations.
   */
 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 method will subscribe the user to the Subscribable
       * passed as argument.
       *
       * S: The Subscribable the user is going to subsribe to.
       *
       *  throw CantSubscribeException : In case the subscription fails,
       * an exception is thrown.
       */
      void subscribeUserTo(Subsribable S) { ... }

      /**
       * Send a message to the user. This can be used for commercial offers
       * or general information about the system.
       *
       * msg: The message you wish to send to the user.
       *
       *  throw MessageNotSentException : If for some reason, the message
 isn't
       * sent properly, a MessageNotSentException is sent.
       */
      sendMessage(string msg) { ... }

 // And so on like forever...
 }

 Mandatory comment block is how you end up with overbloated code like
 this where it is explained to you 3 times in the comment what the
 method's name already tells you. And that is only the begging because
 starting from this point, overtime, comment become more and more out of
 date to ends up looking like an surrealistic form of humor.


I agree with the uselessly overcommented code you describe; I've seen 
plenty of it too.

And yet there is a little room for useful comments here: does getName 
return the user's given/family name or an account username? Possibly 
obviated by the context of whatever app this User class is in, but how 
will the user receive the sent message? Comments on purpose and use can 
save a bit of maintenance developers' time.
Mar 20 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 3:26 PM, deadalnix wrote:

     /**
      * Send a message to the user. This can be used for commercial offers
      * or general information about the system.
      *
      * msg: The message you wish to send to the user.
      *
      *  throw MessageNotSentException : If for some reason, the message isn't
      * sent properly, a MessageNotSentException is sent.
      */
     sendMessage(string msg) { ... }


I'd write it as:

       /**
        * Send message to user. This can be used for commercial offers
        * or general information about the system. The user can receive these
        * messages with the [....] protocol.
        *
        * msg: the message
        *
        *  throw MessageNotSentException : possible reasons are [...]
        *
        * See_Also: receiveMessage()
        */
       sendMessage(string msg) { ... }
Mar 20 2015
prev sibling next sibling parent reply "w0rp" <devw0rp gmail.com> writes:
On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:

 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.


Hear, hear! I start with first with...

public string name;

Then if I really want to change the way the value is assigned or 
maybe add in some validation, possibly with contracts, I use 
 property.

(This is only for things which are supposed to be part of the 
public API anyway.)

I would still document the property, though. I feel I need to 
justify why every member exists in a struct or class. That's 
mainly a data layout concern, and that's just how I happen to 
feel about it.
Mar 20 2015
parent Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Friday, March 20, 2015 11:54:20 w0rp via Digitalmars-d wrote:

 On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:

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


 Hear, hear! I start with first with...

 public string name;

 Then if I really want to change the way the value is assigned or
 maybe add in some validation, possibly with contracts, I use
  property.

 (This is only for things which are supposed to be part of the
 public API anyway.)

 I would still document the property, though. I feel I need to
 justify why every member exists in a struct or class. That's
 mainly a data layout concern, and that's just how I happen to
 feel about it.


In principle, it would be great to be able to do what you're suggesting, but
if you're dealing with a public API, it really doesn't work, because you can
do things with a variable that you can't do with a  property function - like
pass it by ref - and some are legal for both but have different meanings
(e.g. taking its address). So, if you use a public variable as part of the
API, and you want then want to make it so that it does validation later or
so that the value is calculated or anything that would make it so that you
want to use a  property function instead of a public variable, if you change
it to be a  property function, you're probably going to break someone's code
somewhere. So, it really doesn't work to change a public variable into an
 property function later unless you're the only one using the code in
question, or you don't mind breaking other people's code.

Another thing to consider is that the type's invariant will be called on an
 property function, whereas it won't be called when you access a public
variable.

Two possible solutions for this which have been suggested before but never
implemented are:

1. Make it so that if you declare

public  property string name;

it generates a private variable for name (e.g. _name) and getter and setter
property functions called name. So, you don't have to type everything out
explicitly, but you still get the encapsulation.

2. Make it so that if you declare

public  property string name;

it's a public variable as it would normally be, but it's then illegal to do
anything with it that you couldn't do with a property function (e.g. pass it
by ref).

But without a lanugage enhancement of some kind, using public variables in
an API that's being used by anyone else either makes it so that you can't
ever change it so that you're using a property function, even if you need to
later, or you make it so that when you do change it to a property function,
you risk breaking existing code (often, which you don't even know exists,
because it was written by someone else).

- Jonathan M Davis
Mar 20 2015
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 3/19/15 3:03 PM, Walter Bright wrote:

 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; }


They're useful to prevent writes to foo. Also as Amaury mentioned they 
give the implementer better options going forward. See debacle about 
C++'s std::pair's "first" and "second". "Of course they needn't be 
functions!" said everybody to the regret of future everybody. -- Andrei
Mar 20 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/20/2015 5:17 PM, Andrei Alexandrescu wrote:

 They're useful to prevent writes to foo.


That's true.



 Also as Amaury mentioned they give the
 implementer better options going forward. See debacle about C++'s std::pair's
 "first" and "second". "Of course they needn't be functions!" said everybody to
 the regret of future everybody. -- Andrei


Fortunately, D has property functions.
Mar 20 2015
parent "deadalnix" <deadalnix gmail.com> writes:
On Saturday, 21 March 2015 at 00:42:22 UTC, Walter Bright wrote:

 On 3/20/2015 5:17 PM, Andrei Alexandrescu wrote:

 They're useful to prevent writes to foo.


 That's true.



 Also as Amaury mentioned they give the
 implementer better options going forward. See debacle about 
 C++'s std::pair's
 "first" and "second". "Of course they needn't be functions!" 
 said everybody to
 the regret of future everybody. -- Andrei


 Fortunately, D has property functions.


That won't behave the same, because  property is not enforced 
properly, but this is hardly a new topic.
Mar 21 2015
prev sibling parent reply "deadalnix" <deadalnix gmail.com> writes:
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.
Mar 19 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 2:40 AM, deadalnix wrote:

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


I've never seen any code that self-documented "why".
Mar 19 2015
parent reply "deadalnix" <deadalnix gmail.com> writes:
On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:

 On 3/19/2015 2:40 AM, deadalnix wrote:

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


 I've never seen any code that self-documented "why".


Indeed, that is why comment are useful. If all your method
require a why, you probably should consider refactoring instead
of adding comments all over the place.
Mar 19 2015
next sibling parent Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
On Thursday, March 19, 2015 22:27:33 deadalnix via Digitalmars-d wrote:

 On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:

 On 3/19/2015 2:40 AM, deadalnix wrote:

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


 I've never seen any code that self-documented "why".


 Indeed, that is why comment are useful. If all your method
 require a why, you probably should consider refactoring instead
 of adding comments all over the place.


There are plenty of functions that require documentation - especially when
they're more powerful. This is especially true when talking about free
functions rather than member functions. And having documentation for stuff
like what exceptions a function throws can be quite valuable even if the
function's primary functionality doesn't need much explanation. I think that
it's safe to say that most functions need at least minimal documentation.
However, I completely agree that there are a number of functions (especially
property functions and other types of simple accessors) which don't need a
detailed explanation, and having both a main comment on them and a return
and/or param comment on them is redundant and just noise.

So, I fully expect that requiring a return comment or a comment per param
will quickly result in documentation comments being overly verbose. That
being said, most functions do need some sort of documentation, and there are
definitely some functions that will need both the return and param comments
(especially the sort of stuff that goes in std.algorithm).

- Jonathan M Davis
Mar 19 2015
prev sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 3:27 PM, deadalnix wrote:

 On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:

 On 3/19/2015 2:40 AM, deadalnix wrote:

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


 I've never seen any code that self-documented "why".


 Indeed, that is why comment are useful. If all your method
 require a why, you probably should consider refactoring instead
 of adding comments all over the place.


I suppose:



could be renamed to:

     real returnSineOfArumentInRadians_ReturnNanIfNan_
ReturnNanIfInfinity_InvalidIfArgumentIsNanOrInfinity(real x);
Mar 20 2015
prev sibling next sibling parent reply "Brian Schott" <briancschott gmail.com> writes:
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
Mar 18 2015
next sibling parent "Baz" <bb.temp gmx.com> writes:
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


Based on the list: the task should be divided on a per module 
basis. Some modules have a lot of undocumented declaration that 
just need "ditto"; some others recquire specific knowledge (UTF), 
some other simply copy and paste (range things: popFront etc, eg 
"confere with..."). And among them it's not impossible that a few 
items should be private(testUrl1 testUrl2).
Mar 18 2015
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/18/2015 3:05 PM, 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


Thank you!
Mar 19 2015
prev sibling next sibling parent "Kagamin" <spam here.lot> writes:
Indeed, dfmt and/or dfix can handle that just fine. They can also 
try to differentiate between public and private types.
Mar 19 2015
prev sibling parent reply "Don" <x nospam.com> writes:
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.
Mar 19 2015
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Mar 19 2015
parent Jacob Carlborg <doob me.com> writes:
On 2015-03-19 22:55, Walter Bright wrote:


 We already have a special:

      /// ditto

 comment. Perhaps:

      /// undocumented

 ? At least then it would be a deliberate choice.


I would prefer a compiler recognized Ddoc macro, like $(API_PRIVATE) or 
similar.

-- 
/Jacob Carlborg
Mar 20 2015
prev sibling next sibling parent reply "Benjamin Thaut" <code benjamin-thaut.de> writes:
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".
Mar 19 2015
parent reply Martin Nowak <code+news.digitalmars dawg.eu> writes:
On 03/19/2015 11:47 AM, Benjamin Thaut wrote:

 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".


Why would export make private functions public?
Mar 21 2015
parent Benjamin Thaut <code benjamin-thaut.de> writes:
Am 22.03.2015 um 04:40 schrieb Martin Nowak:

 Why would export make private functions public?


Following problem:

// public template
void foo(T)(T arg)
{
   bar(T.sizeof);
}

// private implementation helper
private void bar(size_t size) { ... }


Because bar is used from foo, bar has to be exported, thus the 
protection level has to be changed from "private" to "export". But 
"export" includes "public" so the function bar will now be public as well.

This problem was exessivly discussed here: 
http://forum.dlang.org/thread/m9lhc3$1r1v$1 digitalmars.com

The official response from Walter and Andrei was, that they don't want 
any language change and symbols that need exporting should just become 
public.

But this in turn will mean that tons of currently private helper 
functions without documentation will become public and cause errors or 
warnings in ddoc.

Kind Regards
Benjamin
Mar 22 2015
prev sibling next sibling parent reply "Gary Willoughby" <dev nomad.so> writes:
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.
Mar 19 2015
parent "Charles" <csmith.ku2013 gmail.com> writes:
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?
Mar 19 2015
prev sibling next sibling parent reply "w0rp" <devw0rp gmail.com> writes:
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?
Mar 19 2015
parent Walter Bright <newshound2 digitalmars.com> writes:
On 3/19/2015 12:54 PM, w0rp wrote:

 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?


I consider all the times I have to look up the source code to some "trivial" 
function.
Mar 20 2015
prev sibling next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
On 3/18/15 2:48 PM, 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.


If the idea is to force it on all users, I'm with deadalnix 100%.

But what if -w makes ddoc do this, so you have a choice? Or some other 
switch?

I would also find handy a switch to simply display publicly undocumented 
functions in the documentation. I recently went through and documented 
all core.stdc items with empty docs so they would just show up. Was 
actually quite monotonous.

-Steve
Mar 23 2015
next sibling parent Brad Roberts via Digitalmars-d <digitalmars-d puremagic.com> writes:
Anyone want to do a rough draft version of a script to build with some 
version of what Walter has suggested that produes just a simple number 
for each of druntime and phobos that are the number of undocumented 
functions?

Bonus points for generating a output doc (preferably json) that contains 
useful data about what's missing to facilitate a website for navigating 
through the results.

I'll set it up to run daily and graph and view the results.

On 3/23/2015 12:04 PM, Steven Schveighoffer via Digitalmars-d wrote:

 On 3/18/15 2:48 PM, 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.


 If the idea is to force it on all users, I'm with deadalnix 100%.

 But what if -w makes ddoc do this, so you have a choice? Or some other
 switch?

 I would also find handy a switch to simply display publicly undocumented
 functions in the documentation. I recently went through and documented
 all core.stdc items with empty docs so they would just show up. Was
 actually quite monotonous.

 -Steve
Mar 23 2015
prev sibling parent reply "Daniel Murphy" <yebbliesnospam gmail.com> writes:
"Steven Schveighoffer"  wrote in message 
news:mepo3t$8ka$1 digitalmars.com...


 I would also find handy a switch to simply display publicly undocumented 
 functions in the documentation. I recently went through and documented all 
 core.stdc items with empty docs so they would just show up. Was actually 
 quite monotonous.


A switch like -wi ?
Mar 24 2015
next sibling parent "Kagamin" <spam here.lot> writes:
Another good task for dfix.
Mar 24 2015
prev sibling parent Steven Schveighoffer <schveiguy yahoo.com> writes:
On 3/24/15 7:04 AM, Daniel Murphy wrote:

 "Steven Schveighoffer"  wrote in message
 news:mepo3t$8ka$1 digitalmars.com...


 I would also find handy a switch to simply display publicly
 undocumented functions in the documentation. I recently went through
 and documented all core.stdc items with empty docs so they would just
 show up. Was actually quite monotonous.


 A switch like -wi ?


Does it do this already? I wasn't aware.

-Steve
Mar 24 2015
prev sibling parent reply "Dejan Lekic" <dejan.lekic gmail.com> writes:
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 could take this task, with help of Brian's scanner I could 
easily find that methods to document...

Let me know should I take it or not.
Mar 24 2015
parent "Dejan Lekic" <dejan.lekic gmail.com> writes:
On Tuesday, 24 March 2015 at 14:17:26 UTC, Dejan Lekic 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.


 I could take this task, with help of Brian's scanner I could 
 easily find that methods to document...

 Let me know should I take it or not.


Actually, I just realised what the issue is... :) I apologise. I 
thought the task is to document those functions that are not yet 
documented.

Why would you want DDoc to issue those errors? I would rather 
setup a git hook which is using Brian's dfmt, or implement 
something similar to Checkstyle in Java world, and use it in git 
hook to prevent undocumented functions creeping into the D code...
Mar 24 2015