HaxeFoundation / HaxeFoundation/dox

Embed docs for arguments

Open
#265 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Haxe
Stars
158
Forks
38
PR merge metrics
No merged PRs in 30d

Description

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:

```haxe
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`](https://api.haxe.org/sys/io/FileSeek.html) enum, only used in [`FileInput.seek`](https://api.haxe.org/sys/io/FileInput.html#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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.