Documentation Improvement Initiative

[Andrea Fontana]

On Thursday, 20 February 2020 at 03:32:50 UTC, Mathias Lang wrote:
> On Monday, 17 February 2020 at 12:16:26 UTC, Mike Parker wrote:
>> [...]
> 1. Dub documentation
>
> I agree.
>
> Some of this documentation will *also* require fixes to Dub 
> (e.g. https://github.com/dlang/dub/issues/1474 for anything 
> using preprocessor). There is a feature that allows a project 
> to provide skeleton for apps using it, it might also be useful 
> to try to do it with a few projects.
>
> 2. DMD documentation
>
> I agree. Not only code documentation but also overview & c. 
> It's very difficult to help with dmd development starting from 
> nothing.


I would add a thing. Consider this:

bool isSameLength(Range1, Range2)(Range1 r1, Range2 r2)
if (isInputRange!Range1 && isInputRange!Range2 && 
!isInfinite!Range1 && !isInfinite!Range2);

It's a pretty easy example of a function template. But I guess it 
is quite confusing for a newcomer. Why do we need to focus 
documentation on function signature? Can't we replace the 
function signature as main piece of information with something 
more easier to read for a newcomer?





Andrea