code-d
code-d copied to clipboard
Documentation tooltips different from definition (and http(s) edgecase)
When using a hyperlink starting with http:
/https:
, it is incorrectly regarded as a field .
module app;
import std.stdio;
/**
* http://nu.nl
*/
void main(){
writeln("Test");
}
After some experimentation with generated documentation using dub build --b=docs
(I tried ddox too but I don't understand why my package is not being included in the (hence empty) documentation), it seems to use 2 criteria to identify fields:
- The field starts with a capital letter
- The colon
:
is followed by whitespace
Interestingly enough both these criteria are not mentioned in the specification of ddoc (https://dlang.org/spec/ddoc.html#sections).
Nor does it generate bare URL's. Interestingly enough my tooltip only catches up on hyperlinks starting with www.
/**
Text here
More text
a: https://www.nu.nl
b: https://dlang.org/
*/
void foo(int number){writeln("Test");}
Note also, the first paragraph (Summary) starts the documentation and is followed by a Discussion
section (Actually called Description in the specification).
Summary
To simplify this issue report somewhat here a summary with respect to the tooltips:
-
http
/https
isn't properly being ignored & is interpreted as a section. - The summary & description section are not explicitly shown in the tooltip (though this could save space)
- Bare URL's need to start with
www.
for the tooltip to show them as hyperlinks. - (More of a request)
Params
sections don't show the type in front of the name of a parameter.