Tokens (functions in particular) without doc comments omitted

[jblachly]

Functions (haven't manually verified other types of tokens) without doc comments are omitted from the generated documentation, which is not the behavior IIRC of ddoc nor specified in the adrdox documentation -- and, incidentally speaking of the adrdox documentation, you can only reach the actual documentation from a link provided on the github README: http://dpldocs.info/experimental-docs/adrdox.syntax.html -- if you instead go to http://dpldocs.info/experimental-docs/adrdox.html and click "adrdox syntax," it takes you to the wrong page.

Here is an example of adrdox generated documentation which does not include functions missing doc comments: https://zeromq.dpldocs.info/index.html

[adamdruppe]

That's by design, there's a command line switch to control this,

$ ./doc2 --help | grep docum
-p         --write-private-docs Include documentation for `private` members (default: false)
       --write-internal-modules Include documentation for modules named `internal` (default: false)
        --document-undocumented Generate documentation even for undocumented symbols

The broken link though is an error, it incorrectly thought that was a single-member module and thus skipped it... fixed for now but deeper issue needs attention.

[adamdruppe]

But the logic is that undocumented functions are... well, undocumented. So it won't force them to display unless you opt into putting it up there with at least an empty comment or with that --document-undocumented switch.

But there's another regression in here too oh dear. All because of the leading spam garbage. ugh i gotta fix that

[jblachly]

Given that dpldocs is generated automatically from the registry, and that many registry users may not be aware of this difference-from-default, do you think that may be surprising and undesireable to package authors?

[jblachly]

(to be clear I am not asking you to change the behavior or default behavior of adrdox, but perhaps consider adding the flag for packages run from the registry and sent to dpldocs.info)

[adamdruppe]

ddoc also doesn't show undocumented functions and this is expressly stated by the ddoc spec: section 31.3.3 paragraph 3: "If there is no documentation comment for a declaration, that declaration may not appear in the output. To ensure it does appear in the output, put an empty declaration comment for it." https://dlang.org/spec/ddoc.html#parsing

But curiously adrdox does show some of that zeromq package.... and I don't know why... like it shows zmq_join but not zmq_leave which is right next to it. That's bizarre.... I think the comment from the preceding anonymous enum is incorrectly retained for the following declaration too. Bug!

But regardless of what dmd does; I'm outright breaking the ddoc spec in other places, it is fair to ask what is the most useful behavior. druntime's C bindings are the reason why I added document-undocumented but the result was never really great. It'd end up generating a lot of useless stuff, especially with druntime's several OS versions.

I tried to detect extern(C) and automatically link back and/or import docs from C too and that didn't work out.

I suppose one possibility would be:

• document the undocumented things and document that they were undocumented. In other words, explicitly call out in the generated file that there wasn't a doc comment attached, meaning the function might be internal, legacy, etc. So the user knows the author isn't necessarily committing to support this, despite it showing up.

• If it is extern(C), auto-generate a note that says it it is a binding to a C function and you may be able to learn more about it by searching the web.

• Try to educate package authors about it so they do a better job documenting their apis.

• Accept that this isn't going to give great results in any case, and might be bad in some case, but hopefully better than nothing in more cases than worse than nothing.

I'm open to that, but it is bed time for me right now.

[jblachly]

Thanks for this reasoned response; I was clearly mistaken about dmd ddoc behavior.

I am particularly sensitive to the arguments related to bindings, being primarily a producer (https://github.com/blachlylab/dhtslib) and consumer of C bindings.

Interestingly the C bindings in zmq which prompted this issue include /* */ C style comments; as you note clearly the authors of the C headers intended these public interfaces to be documented.

Anyway thanks for your consideration and for dpldocs.info generally.

[adamdruppe]

I'm working on this right now btw you can see it slowly starting to come together here http://dpldocs.info/experimental-docs/test.sif.undocumentedObjc.html

gotta get back to day job work soon but i think ill have this live today.

[adamdruppe]

https://zeromq.dpldocs.info/deimos.zmq.zmq.html

well... it isn't great but it isn't bad. It exposed another bug though apparently the extern(C) in adrdox got lost underneath a version specifier. Fun another thing to fix.

But it shows the full list now at least.