I assume you don't mean the documentation for std.array specifically,
but the act of having documentation of the module.

Then, yes I do think documentation should not be needed.

I think it would be far better if I only needed the signatures of
the functions and the members of the structs to use them.
That I need to look at an example usage of a function to grasp its
meaning or read some text about it, is not a good sign IMHO.

Please keep in mind, I'm striving for an ideal, not reality.
dud will be documented, no question about it.
But I think, the longer documentation is not needed to understand
dud, the better.

p.s. I find it hard to explain this in writing.
It makes perfect sense in my head. Maybe I can convince you in person
at the next dconf.

On Wednesday, 20 November 2019 at 13:37:39 UTC, Jacob Carlborg wrote:
> On Wednesday, 20 November 2019 at 11:40:19 UTC, Robert Schadek wrote:
>
>> Here is disagree, to a degree I consider comments a code smell.
>> If I have to write them, I failed to convey the information
>> needed to understand the code in the code.
>
> You think this is a code smell: https://dlang.org/phobos/std_array.html ?
>
> --
> /Jacob Carlborg

When a function signature looks like this

ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, scope R sep)
if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && isInputRange!R && is(Unqual!(ElementType!(ElementType!RoR)) == Unqual!(ElementType!R)))

or like this:

E[] replaceFirst(E, R1, R2)(E[] subject, R1 from, R2 to)
if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(from[0..1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(to[0..1]))));

it's understandable why documentation is mandatory.

On Wednesday, 20 November 2019 at 16:29:20 UTC, Rumbu wrote:
>
> When a function signature looks like this
>
> ElementEncodingType!(ElementType!RoR)[] join(RoR, R)(RoR ror, scope R sep)
> if (isInputRange!RoR && isInputRange!(Unqual!(ElementType!RoR)) && isInputRange!R && is(Unqual!(ElementType!(ElementType!RoR)) == Unqual!(ElementType!R)))
>
> or like this:
>
> E[] replaceFirst(E, R1, R2)(E[] subject, R1 from, R2 to)
> if (isDynamicArray!(E[]) && isForwardRange!R1 && is(typeof(appender!(E[])().put(from[0..1]))) && isForwardRange!R2 && is(typeof(appender!(E[])().put(to[0..1]))));
>
> it's understandable why documentation is mandatory.

That's true, Rumbu!

And despite that, it's always marvel me the fact that I can simply read the above and actually "understand it"!

It's some kind of magic, but maybe it's simply why I'm forced to read too much C++ recently...  :-P

PS ... the most difficult part for a beginner maybe is the historical "is(typeof( ... bla bla ...)"

On Wednesday, 20 November 2019 at 11:40:19 UTC, Robert Schadek wrote:
> Here is disagree, to a degree I consider comments a code smell.
> If I have to write them, I failed to convey the information
> needed to understand the code in the code.

That depends on what you're using documentation and comments for.

It's obviously great to try to write code that is as clean and clear and comprehensible as possible.  But in general even the cleanest and clearest code rarely communicates the WHY behind design decisions.  "This design was chosen because ..."  "These are the assumptions made ..." etc.

That WHY is what you want to clearly document, because that's what saves the most time for anyone looking to understand and modify the codebase.

On 11/20/19 6:40 AM, Robert Schadek wrote:
>> * for the same reasons, really try to provide good documentation and comments
>>     for all code from the start -- this really makes it much easier for anyone
>>     interested to grasp the major design concerns and get contributing
> 
> Here is disagree, to a degree I consider comments a code smell.
> If I have to write them, I failed to convey the information
> needed to understand the code in the code.

Assuming the code you wrote does what you wanted it to do...

Often times, comments convey what you're thinking, and it's much easier to understand a description than mentally compiling and running the code to figure out what you were thinking.

-Steve

On Thursday, 21 November 2019 at 14:50:59 UTC, Steven Schveighoffer wrote:
> Assuming the code you wrote does what you wanted it to do...
>
> Often times, comments convey what you're thinking, and it's much easier to understand a description than mentally compiling and running the code to figure out what you were thinking.

Exactly.  And of course this isn't just for the benefit of others -- future you often needs the exact same help to understand what past you was thinking ...

On Monday, 18 November 2019 at 16:54:21 UTC, JN wrote:
>> Personally I only ever use SDL with Dub. Even contemplating using JSON for human written configuration files is, for me, totally the wrong thing to do.
>
> I only use the JSON format. JSON is widespread together with XML. SDL I heard first time of in the context of Dub and never seen it used elsewhere. TOML also I know only from Cargo. YAML at least I know from several different projects.
>
> I guess the tool must be working very well though if the main argument is what kind of data format to use :)

I also only ever use JSON. When SDL was introduced, it was promised "JSON will never be deprecated". And here people are wanting to deprecate JSON as if SDL parsers were all that numerous.

JSON is the answer, SDL is the failed experiment that just bring disagreement :)

We DO parse dub.json a lot. I suspect any D organization probably does because dub describe is slow.

I don't care how "inhuman" a 20-line file is.

On 23/11/2019 4:37 AM, Guillaume Piolat wrote:
> On Monday, 18 November 2019 at 16:54:21 UTC, JN wrote:
>>> Personally I only ever use SDL with Dub. Even contemplating using JSON for human written configuration files is, for me, totally the wrong thing to do.
>>
>> I only use the JSON format. JSON is widespread together with XML. SDL I heard first time of in the context of Dub and never seen it used elsewhere. TOML also I know only from Cargo. YAML at least I know from several different projects.
>>
>> I guess the tool must be working very well though if the main argument is what kind of data format to use :)
> 
> I also only ever use JSON. When SDL was introduced, it was promised "JSON will never be deprecated". And here people are wanting to deprecate JSON as if SDL parsers were all that numerous.
> 
> JSON is the answer, SDL is the failed experiment that just bring disagreement :)
> 
> We DO parse dub.json a lot. I suspect any D organization probably does because dub describe is slow.
> 
> I don't care how "inhuman" a 20-line file is.

+1

On Saturday, 23 November 2019 at 03:57:02 UTC, rikki cattermole wrote:
> On 23/11/2019 4:37 AM, Guillaume Piolat wrote:
>> On Monday, 18 November 2019 at 16:54:21 UTC, JN wrote:
>>>> Personally I only ever use SDL with Dub. Even contemplating using JSON for human written configuration files is, for me, totally the wrong thing to do.
>>>
>>> I only use the JSON format. JSON is widespread together with XML. SDL I heard first time of in the context of Dub and never seen it used elsewhere. TOML also I know only from Cargo. YAML at least I know from several different projects.
>>>
>>> I guess the tool must be working very well though if the main argument is what kind of data format to use :)
>> 
>> I also only ever use JSON. When SDL was introduced, it was promised "JSON will never be deprecated". And here people are wanting to deprecate JSON as if SDL parsers were all that numerous.
>> 
>> JSON is the answer, SDL is the failed experiment that just bring disagreement :)
>> 
>> We DO parse dub.json a lot. I suspect any D organization probably does because dub describe is slow.
>> 
>> I don't care how "inhuman" a 20-line file is.
>
> +1
+1, and JSON as a main format would make sense too because querying information from DUB registry is already being done in JSON, so throwing in SDL would complicate things.

There's also plenty of JSON parsers out there, some of them being extremely performant (like fast.json and asdf), but only one (AFAIK) SDL parser with no ideas how fast it is. The performance should not be ignored as every build operation requires parsing all of the dependencies and their dependencies too which can quickly accumulate with larger complicated projects.

The easy of modifying SDL vs JSON is a non-issue for me, you don't spend that much time editing the configuration files while developing your project.

Regarding dependency resolution:

Did anybody here had a look at what the Dart people are
doing with pubgrab?

https://github.com/dart-lang/pub/blob/master/doc/solver.md
https://medium.com/@nex3/pubgrub-2fb6470504f
https://www.youtube.com/watch?v=Fifni75xYeQ

Especially the error reporting looks promising to me.