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: http://dlang.org/phobos/std_math.html#.sin 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