Skip to content

Documentation tooltips different from definition (and http(s) edgecase) #405

@HuskyNator

Description

@HuskyNator

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");
}

image

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:

  1. The field starts with a capital letter
  2. 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");}

image

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions