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
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
Another good task for dfix.
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
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
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
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
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'
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
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
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?
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
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
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
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,
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
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.
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
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,
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
*/
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
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
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
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
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
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() { ... }
/**
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,
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,
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
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
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
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.
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
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.
Indeed, dfmt and/or dfix can handle that just fine. They can also
try to differentiate between public and private types.
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
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
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
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
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.
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
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
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,
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
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
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
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
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
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
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.
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
51 matches
Mail list logo
