Embed docs for arguments

[Aurel300]

As discussed on Slack, I think it would be good if there was a way to "embed" the docs for the type of certain arguments visually into the docs for that method. As an example:

typedef FooOptions = {
  /**
  * something about boo
  **/
  var boo:String;

  /**
  * something about bar
  **/
  var bar:Int;
};

class Foo {
  /**
  * description of doStuff
  * @param options
  **/
  public static function doStuff(?options:FooOptions):Void;
}

Currently dox would generate a page for FooOptions and a page for Foo. To find out what the options for doStuff are, the user needs to click through FooOptions to see the description of individual options. This is reasonable for types in general, but specifically for options-like struct types like this, it is impractical – the struct type is only used for that method and nothing else.

There are multiple cases of this in the upcoming asys APIs (to avoid having a huge amount of optional arguments). A non-struct type in the current standard library is the FileSeek enum, only used in FileInput.seek.

I would suggest adding a doc "meta" like @embedParam rather than @param (or in addition to @param) that would cause dox to generate the method description as normal, but put the full type doc of the relevant type in place of the usual argument description. The result would be a single page on which the user sees the description of the method as well as its specific options or enums, without causing issues to IDE completion.

[dpeek]

Might be better to implement a tooltip preview providing basic type information, as it solves this problem and in quite useful in general.

[Aurel300]

I disagree with that. It may be a useful thing to remind yourself of what a particular type is at a glance. But it is not good enough to read the entire doc for the type. Consider the options type in this (old) asys function: Process.spawn.