digitalmars.D - Enhancement: issue error on all public functions that are missing
- Walter Bright (3/3) Mar 18 2015 I'm fed up with this problem. It is actively hurting us every day.
- Jacob Carlborg (8/11) Mar 18 2015 I'm not so sure about this. I think there's a big chance that users will...
- Walter Bright (11/17) Mar 18 2015 Right, but then it becomes glaringly obvious in the Pull Request and eas...
- Jacob Carlborg (5/6) Mar 18 2015 It's tremendously useful for reporting other issues. I can configure the...
- Andrei Alexandrescu (2/10) Mar 18 2015 That won't pass review. -- Andrei
- Jacob Carlborg (5/6) Mar 19 2015 If that's the case, how did an undocumented symbol pass review in the
- deadalnix (20/34) Mar 19 2015 Here is what will pass review :
- Brian Schott (5/7) Mar 19 2015 Garbage like this is why Harbored treats the "Returns:" section
- Walter Bright (6/22) Mar 19 2015 Accessor functions that merely return a field variable are bull anyway.
- Jeremy Powers via Digitalmars-d (12/15) Mar 19 2015 I would recommend against opening up this debate. Suffice it to say tha...
- bachmeier (8/11) Mar 19 2015 I'm not a big fan of that. It's one of those slippery slope
- deadalnix (6/17) Mar 19 2015 Ok let's be clear. This kind of overpedantic commenting is a good
- Walter Bright (2/5) Mar 20 2015 Right, it's also to support automated tooling.
- Andrei Alexandrescu (10/16) Mar 20 2015 I also appreciate that whenever I go in some function like
- Andrei Alexandrescu (2/6) Mar 20 2015 Makes sense. -- Andrei
- Kagamin (4/9) Mar 20 2015 That's a non-obvious property worth documenting. If it's a public
- Walter Bright (2/5) Mar 20 2015 That's why D has properties. Fields can be replaced with property functi...
- Steven Schveighoffer (4/12) Mar 23 2015 Replacing fields for properties and vice versa is an incompatible API
- deadalnix (52/71) Mar 19 2015 That is completely missing the point. If that is not clear enough
- David Gileadi (8/78) Mar 20 2015 I agree with the uselessly overcommented code you describe; I've seen
- Walter Bright (14/24) Mar 20 2015 I'd write it as:
- w0rp (12/31) Mar 20 2015 Hear, hear! I start with first with...
- Jonathan M Davis via Digitalmars-d (35/50) Mar 20 2015 In principle, it would be great to be able to do what you're suggesting,...
- Andrei Alexandrescu (5/29) Mar 20 2015 They're useful to prevent writes to foo. Also as Amaury mentioned they
- Walter Bright (3/8) Mar 20 2015 Fortunately, D has property functions.
- deadalnix (3/13) Mar 21 2015 That won't behave the same, because @property is not enforced
- deadalnix (4/15) Mar 19 2015 It is not a good chance, it is 100% guaranteed.
- Walter Bright (2/4) Mar 19 2015 I've never seen any code that self-documented "why".
- deadalnix (4/9) Mar 19 2015 Indeed, that is why comment are useful. If all your method
- Jonathan M Davis via Digitalmars-d (17/27) Mar 19 2015 There are plenty of functions that require documentation - especially wh...
- Walter Bright (6/15) Mar 20 2015 I suppose:
- Brian Schott (4/9) Mar 18 2015 D-Scanner has had this feature for a while. Here's the list for
- Baz (7/19) Mar 18 2015 Based on the list: the task should be divided on a per module
- Walter Bright (2/10) Mar 19 2015 Thank you!
- Kagamin (2/2) Mar 19 2015 Indeed, dfmt and/or dfix can handle that just fine. They can also
- Don (7/19) Mar 19 2015 That's a very interesting list. Things like this:
- Walter Bright (6/9) Mar 19 2015 We already have a special:
- Jacob Carlborg (5/10) Mar 20 2015 I would prefer a compiler recognized Ddoc macro, like $(API_PRIVATE) or
- Benjamin Thaut (4/9) Mar 19 2015 This is going to be a lot of fun as soon as tons of currently
- Martin Nowak (2/4) Mar 21 2015 Why would export make private functions public?
- Benjamin Thaut (22/23) Mar 22 2015 Following problem:
- Gary Willoughby (4/9) Mar 19 2015 I would like this but issue warnings not errors. I like every
- Charles (3/7) Mar 19 2015 Why not just make unittests mandatory, and completely forego the
- w0rp (5/10) Mar 19 2015 I think this is a good idea. Even the most trivial looking
- Walter Bright (3/7) Mar 20 2015 I consider all the times I have to look up the source code to some "triv...
- Steven Schveighoffer (9/12) Mar 23 2015 If the idea is to force it on all users, I'm with deadalnix 100%.
- Brad Roberts via Digitalmars-d (9/23) Mar 23 2015 Anyone want to do a rough draft version of a script to build with some
- Daniel Murphy (3/7) Mar 24 2015 A switch like -wi ?
- Kagamin (1/1) Mar 24 2015 Another good task for dfix.
- Steven Schveighoffer (3/10) Mar 24 2015 Does it do this already? I wasn't aware.
- Dejan Lekic (4/9) Mar 24 2015 I could take this task, with help of Brian's scanner I could
- Dejan Lekic (8/20) Mar 24 2015 Actually, I just realised what the issue is... :) I apologise. I
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
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
On 3/18/2015 12:28 PM, Jacob Carlborg wrote:Right, but then it becomes glaringly obvious in the Pull Request and easier to reject.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.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
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
On 3/18/15 12:28 PM, Jacob Carlborg wrote:On 2015-03-18 19:48, Walter Bright wrote:That won't pass review. -- AndreiI'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.
Mar 18 2015
On 2015-03-18 20:43, Andrei Alexandrescu wrote:That won't pass review. -- AndreiIf that's the case, how did an undocumented symbol pass review in the first place? -- /Jacob Carlborg
Mar 19 2015
On Wednesday, 18 March 2015 at 19:43:47 UTC, Andrei Alexandrescu wrote:On 3/18/15 12:28 PM, Jacob Carlborg wrote: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 2015-03-18 19:48, Walter Bright wrote:That won't pass review. -- AndreiI'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.
Mar 19 2015
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
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
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
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
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: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.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
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
On 3/20/15 4:26 PM, Walter Bright wrote:On 3/19/2015 5:08 PM, deadalnix wrote: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>. AndreiOk 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
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
On Thursday, 19 March 2015 at 22:14:02 UTC, Jeremy Powers wrote: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.int foo; int getFoo() { return foo; }A valid reason for doing things like this is future-proof encapsulation.
Mar 20 2015
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
On 3/20/15 7:25 PM, Walter Bright wrote:On 3/19/2015 3:13 PM, Jeremy Powers via Digitalmars-d wrote:Replacing fields for properties and vice versa is an incompatible API change. -SteveA 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 23 2015
On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:On 3/19/2015 2:43 AM, deadalnix wrote: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.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.
Mar 19 2015
On 3/19/15 3:26 PM, deadalnix wrote:On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote: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.On 3/19/2015 2:43 AM, deadalnix wrote: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.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.
Mar 20 2015
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
On Thursday, 19 March 2015 at 22:04:01 UTC, Walter Bright wrote:On 3/19/2015 2:43 AM, deadalnix wrote: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.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.
Mar 20 2015
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: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 DavisAccessor 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
On 3/19/15 3:03 PM, Walter Bright wrote:On 3/19/2015 2:43 AM, deadalnix wrote: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. -- AndreiHere 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 20 2015
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. -- AndreiFortunately, D has property functions.
Mar 20 2015
On Saturday, 21 March 2015 at 00:42:22 UTC, Walter Bright wrote:On 3/20/2015 5:17 PM, Andrei Alexandrescu wrote:That won't behave the same, because property is not enforced properly, but this is hardly a new topic.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. -- AndreiFortunately, D has property functions.
Mar 21 2015
On Wednesday, 18 March 2015 at 19:28:44 UTC, Jacob Carlborg wrote:On 2015-03-18 19:48, Walter Bright wrote: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.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.
Mar 19 2015
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
On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:On 3/19/2015 2:40 AM, deadalnix wrote: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.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
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: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 DavisOn 3/19/2015 2:40 AM, deadalnix wrote: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.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
On 3/19/2015 3:27 PM, deadalnix wrote:On Thursday, 19 March 2015 at 22:05:51 UTC, Walter Bright wrote:I suppose: could be renamed to: real returnSineOfArumentInRadians_ReturnNanIfNan_ ReturnNanIfInfinity_InvalidIfArgumentIsNanOrInfinity(real x);On 3/19/2015 2:40 AM, deadalnix wrote: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.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 20 2015
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
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: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).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
On 3/18/2015 3:05 PM, Brian Schott wrote:On Wednesday, 18 March 2015 at 18:48:53 UTC, Walter Bright wrote:Thank you!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 19 2015
Indeed, dfmt and/or dfix can handle that just fine. They can also try to differentiate between public and private types.
Mar 19 2015
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: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.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 19 2015
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
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
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
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
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
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
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
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
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
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
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
"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
On 3/24/15 7:04 AM, Daniel Murphy wrote:"Steven Schveighoffer" wrote in message news:mepo3t$8ka$1 digitalmars.com...Does it do this already? I wasn't aware. -SteveI 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
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
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: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...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