Improving the D documentation web presentation

[WebFreak001]

On Wednesday, 27 May 2020 at 06:38:46 UTC, Andre Pany wrote:
> On Monday, 25 May 2020 at 16:12:14 UTC, Andrei Alexandrescu 
> wrote:
>> On 5/25/20 9:56 AM, WebFreak001 wrote:
>>> What is your thought on the current ddox and ddoc 
>>> documentation? Which one do you like and/or use more?
>>
>> Lots of chatter about that over the years. I grew to 
>> appreciate having both options. (We're not alone, e.g. GNU 
>> does the same.)
>
> Unfortunately while searching for `dlang spawnShell` or 
> similar, the first hit on google is 
> https://dlang.org/library/std/process/spawn_shell.html
>
> The function description is not that good:
> Pid spawnShell (
>   scope const(char)[] command,
>   File stdin = makeGlobal(),
>   File stdout = makeGlobal(),
>   File stderr = makeGlobal(),
>   scope const(string[string]) env = 
> cast(const(string[string]))null,
>   Config config = cast(Config)0,
>   scope const(char)[] workDir = null,
>   scope string shellPath = nativeShell()
> ) @trusted;
>
> comparing to 
> https://dlang.org/phobos/std_process.html#spawnShell
>
> @trusted Pid spawnShell(scope const(char)[] command, File stdin 
> = std.stdio.stdin, File stdout = std.stdio.stdout, File stderr 
> = std.stdio.stderr, scope const string[string] env = null, 
> Config config = Config.none, scope const(char)[] workDir = 
> null, scope string shellPath = nativeShell);
>
> As I know this issue, I refuse to use the first hit on google, 
> but for other users, this
> is quite confusing / disturbing I assume.
>
> Kind regards
> André

oh yep you are right, the values are quite a mess. I just 
searched for "dlang run program" as I would imagine some newcomer 
might do. After "Run D program locally - Dlang Tour" the second 
link is https://dlang.org/library/std/process/execute.html


auto Tuple!(int,"status",string,"output") execute (
   scope const(char[])[] args,
   const(string[string]) env = cast(const(string[string]))null,
   Config config = cast(Config)0,
   ulong maxOutput = 18446744073709551615LU,
   scope const(char)[] workDir = null
) @trusted;

auto Tuple!(int,"status",string,"output") execute (
   scope const(char)[] program,
   const(string[string]) env = cast(const(string[string]))null,
   Config config = cast(Config)0,
   ulong maxOutput = 18446744073709551615LU,
   scope const(char)[] workDir = null
) @trusted;


Compared to


@trusted auto execute(scope const(char[])[] args, const 
string[string] env = null, Config config = Config.none, size_t 
maxOutput = size_t.max, scope const(char)[] workDir = null);

@trusted auto execute(scope const(char)[] program, const 
string[string] env = null, Config config = Config.none, size_t 
maxOutput = size_t.max, scope const(char)[] workDir = null);

@trusted auto executeShell(scope const(char)[] command, const 
string[string] env = null, Config config = Config.none, size_t 
maxOutput = size_t.max, scope const(char)[] workDir = null, 
string shellPath = nativeShell);


Things I would like to see improved on the documentation page in 
general:
- use structured standard sections (See_Also, Examples)
   - maybe automatically generate See_Also from mentioned symbols 
too
- maybe a copy of the module documentation? It's exactly what I 
had searched for (see https://dlang.org/phobos/std_process.html) 
and I think it would improve discovery in the ddox style 
documentation. Some module documentation might need to be 
adjusted and general examples should probably be omitted.
- we need much more full examples per function! Compare this to 
the C# documentation which has like examples for every property 
of commonly used types.
   - to avoid code duplication for this, we need some way to embed 
examples or other documentation as references inside documentation


Also as an example for a better documented signature of that 
execute function to show to a beginner I would suggest:


auto Tuple!(int,"status", string,"output") execute(
   scope const(char[])[]  args,
   const string[string]   env       = null,
         Config           config    = Config.none,
         ulong            maxOutput = size_t.max,
   scope const(char)[]    workDir   = null
) @trusted;

auto Tuple!(int,"status", string,"output") execute(
   scope const(char)[]    program,
   const string[string]   env       = null,
         Config           config    = Config.none,
         ulong            maxOutput = size_t.max,
   scope const(char)[]    workDir   = null
) @trusted;


* fixed the default values (made them like in the ddoc docs)
* made const for an entire type format like scope (I think it's 
more obvious what it means in a formatted context like this)
* horizontally aligned scope/const/in/out, type, argument name, 
default value
* horizontally aligned across all definitions
* special formatting for Tuple because it's a common type