Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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...
Re: Enhancement: issue error on all public functions that are missing ddoc sections
Another good task for dfix.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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 ?
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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?
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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) { ... }
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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);
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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 voicethey were a bit redundant/mock whiny voice or mock whiny voicethat's repetitive/mock whiny voice. Andrei
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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; }
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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!
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
Indeed, dfmt and/or dfix can handle that just fine. They can also try to differentiate between public and private types.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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?
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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?
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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).
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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.
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
Re: Enhancement: issue error on all public functions that are missing ddoc sections
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
