[Issue 17171] ddoc: enum misses some values + wrong order + missing member initializers

[d-bugmail at puremagic.com]

https://issues.dlang.org/show_bug.cgi?id=17171

Andrew Edwards <edwards.ac at gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |edwards.ac at gmail.com

--- Comment #2 from Andrew Edwards <edwards.ac at gmail.com> ---
(In reply to Timothee Cour from comment #0)
> std.process.d:
> ```
> enum Config
> {
>     none = 0,
> ...
> }
> ```
> 
> https://dlang.org/library/std/process/config.html:

This url points to the documentation generated by DDOX not DDOC this issue
implies. The DDOC documentation. The actual DDOC url is [1].

> * A1 the `none` entry doesn't appear.

`none` is not documented, hence why it's not showing up. The question is,
should it be documented? If it's just a matter of showing up for completeness,
`///` should do the trick.

> * A2 the entries are out of order

Not the case in the DDOX version [1]. This is an issue that probably needs to
be filed at [2].

> * A3 the automatic splitting with a hyphen (re-tain-Stderr) is very
> annoying, at least use a bigger margin than 6

I do not see this issue in either the DDOC or DDOX version of the
documentation. If this problem still exists, please provide a link.

> * A4 the member initializers are not shown
> For A4, https://issues.dlang.org/show_bug.cgi?id=9695 was marked as closed
> however it's very arguable, it could be part of documentation (even if with
> a CAVEAT mentioning implementation detail); for example: I reopened
> https://issues.dlang.org/show_bug.cgi?id=129 because the enums in ddoc are
> downgraded to their integral counterparts, which creates a catch 22
> situation, since we can't look up the enum values from ddoc because of A4 !

This, again, is not a DDOC issue but rather a DDOX issue. Issue 129 is resolved
and should be closed. You are looking at the wrong location for the result.
Look at [1] instead.

The real issue is there are two public-facing versions of the documentation.
What is the intent? Is it to replace DDOC? If so, who is leading the effort?
What issues are preventing us from moving forward? What can I do to assist in
the process? I don't think it's got at all to have to public-facing versions of
the same documentation that conflict with each other.

In light of the information provided, this issue should be closed. Accordingly,
both issues https://issues.dlang.org/show_bug.cgi?id=129 and
https://issues.dlang.org/show_bug.cgi?id=9695 should be close. The perceived
problem mentioned in comment 6 of issue 9695 does not exist, the user is merely
looking at the wrong version of the documentation. If there are no objections,
I will close in all three issues in 1 week. I do however desire to hear the
response to the questions posed. 

[1] https://dlang.org/phobos/std_process.html#.Config
[2] https://github.com/dlang/dub/issues

--