search

wilzbach / tools-test

1 stars 0 forks source link

ddoc: enum misses some values + wrong order + missing member initializers #164

Closed wilzbach closed 7 years ago

wilzbach commented 7 years ago

Note: the issue was created automatically migrated from https://issues.dlang.org

Original bug ID: BZ#17171 From: Timothee Cour <timothee.cour2@gmail.com> Reported version: D2 CC: doob@me.com, edwards.ac@gmail.com

wilzbach commented 7 years ago

Comment author: Timothee Cour <timothee.cour2@gmail.com>

std.process.d:

enum Config
{
    none = 0,
...
}

https://dlang.org/library/std/process/config.html:

wilzbach commented 7 years ago

Comment author: Jacob Carlborg <doob@me.com>

(In reply to Timothee Cour from comment BZ#0)

  • A1 the none entry doesn't appear.

As far as I can see, "none" is not documented.

wilzbach commented 7 years ago

Comment author: Andrew Edwards <edwards.ac@gmail.com>

(In reply to Timothee Cour from comment BZ#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