On 3/20/15 4:26 PM, Walter Bright wrote:
> On 3/19/2015 5:08 PM, deadalnix wrote:
>> Ok let's be clear. This kind of overpedantic commenting is a good
>> thing in a
>> public, widespread API, like phobos's. Especially since you can generate
>> documentation from it, this is going to be googled for.
>
> Right, it's also to support automated tooling.

I also appreciate that whenever I go in some function like http://linux.die.net/man/3/popen I see the same uniform format. My purpose is not to write an exegesis of the documentation, but to just use the blessed function and be on my way.

I'd be super annoyed if whoever wrote the documentation chose to eliminate some sections for some functions just because <mock whiny voice>"they were a bit redundant"</mock whiny voice> or <mock whiny voice>"that's repetitive"</mock whiny voice>.


Andrei

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.

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?

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

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

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

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

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

Another good task for dfix.

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