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

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

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.

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: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) { ... }

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.

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

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

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.