Improvements to hover hints (support more doc tags)

[EliteMasterEric]

I think that adding some new features to the hover hints for VSCode would drastically improve the ability to write concise documentation.

Context

Hover Hints display the documentation of variables you hover over. This is useful for quickly learning more about a given class.

The following tags are already supported with VSCode's Haxe integration:

• @deprecated [reason or alternative]
• @return [description of return value] (@returns works the same with the last tag taking precedence)
• @param [name] [description of param]
• @exception [name] [description of exception] (@throws works the same)
• @event [name] [description of event]
• @since [version]
• @see [text or link]

A preview of all these options:

Suggestion

JavaDoc and Doxygen support many more tags than what Haxe docs do. I am not aware of how VSHaxe implements these, and to what extent these are the responsibility of VSCode itself, VSHaxe, CodeDox, or the language server to provide support for.

A description of tags, some or all of which would be a great fit for VSHaxe:

• @author [author name] displays an indented paragraph with the author(s) of a class or function. Supports multiple lines, or multiple @author tags will be combined into multiple lines. See Doxygen
• @version []
• @link allows for the documentation of one class or field to link to another. See Doxygen
  • For example, {@link java.awt.Panel} links to the Panel class and clicking the link takes you to its source code.
• @note [notice for user] displays an indented paragraph headed with "Note", with no other special structure. See Doxygen
  • @warning and @attention act similarly
• @value displays the current value, if the field is final and primative.
• Other useful tags exist but mainly for doc generation, such as @image or @bug.

An example of what link looks like in JavaDoc. Clicking the hyperlink will take the user to that function's definition.

An example of what value looks like in JavaDoc. Hovering over PI will display "The value of PI is 3.14." in the IDE or in generated docs.

These are some of the other features I might like to see:

• Support using \ for tags rather than @, for users who are used to C++ or copying code from an existing project.
• Allow placing documentation after members, good for one-line fields like so: public var position(get, set):Float; /**< Detailed description after the member */

Additional Notes

For those looking to implement this (or maybe my future self when I have more time), I believe this is one of the relevant lines of code but there must be more too I think?

• https://github.com/vshaxe/haxe-language-server/blob/master/src/haxeLanguageServer/helper/JavadocHelper.hx

Here are some notes on the tags JavaDoc and Doxygen support:

• https://doxygen.nl/manual/commands.html

[Gama11]

I have a bit of a personal vendetta against @author tags, peopele never update them, and that's what version control is for anyway. ;)

[EliteMasterEric]

I have a bit of a personal vendetta against @author tags, peopele never update them, and that's what version control is for anyway. ;)

Honestly, that's fair. The same logic applies to @version too.

However I do really like @link in particular.