Side navigation
#791 closed enhancement (invalid)
Opened January 12, 2007 10:54AM UTC
Closed February 05, 2010 08:19PM UTC
Cross-reference API documentation
| Reported by: | joern | Owned by: | |
|---|---|---|---|
| Priority: | major | Milestone: | |
| Component: | docs | Version: | |
| Keywords: | Cc: | ||
| Blocked by: | Blocking: |
Description
A good API documentations needs cross-reference. A possible format for the inline documentation would use the @see format:
/** * ... * @see otherMethod(Arguments) */
To implement this, we have to define a format that is easy to write and not ambigous. So far all methods can be distinguished by their argument types, for example, the various $ implementations share the same name with different arguments:
@see $(String) @see $(String, Element|jQuery) @see $(Element|Array<Element>) @see $(Function)
Those identifies must be converted to the hash identifies that the Mediawiki generates:
#.24.28_html_.29 #.24.28_expr.2C_context_.29 #.24.28_fn_.29 #.24.28_elems_.29
Currently the wiki uses the argument names to identify methods, I'd prefer that to be changed to argument types.
It has to be considered to mix both, though I see the drawback here of increased effort to write and maintain the @see tags, while it may be easier to understand for the reader what is expected.
Attachments (0)
Change History (1)
Changed February 05, 2010 08:19PM UTC by comment:1
| description: | A good API documentations needs cross-reference. A possible format for the inline documentation would use the @see format:\ \ {{{\ /**\ * ...\ * @see otherMethod(Arguments)\ */\ }}}\ \ To implement this, we have to define a format that is easy to write and not ambigous. So far all methods can be distinguished by their argument types, for example, the various $ implementations share the same name with different arguments:\ \ {{{\ @see $(String)\ @see $(String, Element|jQuery)\ @see $(Element|Array<Element>)\ @see $(Function)\ }}}\ \ Those identifies must be converted to the hash identifies that the Mediawiki generates:\ \ {{{\ #.24.28_html_.29\ #.24.28_expr.2C_context_.29\ #.24.28_fn_.29\ #.24.28_elems_.29\ }}}\ \ Currently the wiki uses the argument names to identify methods, I'd prefer that to be changed to argument types.\ \ It has to be considered to mix both, though I see the drawback here of increased effort to write and maintain the @see tags, while it may be easier to understand for the reader what is expected. → A good API documentations needs cross-reference. A possible format for the inline documentation would use the @see format: \ \ {{{ \ /** \ * ... \ * @see otherMethod(Arguments) \ */ \ }}} \ \ To implement this, we have to define a format that is easy to write and not ambigous. So far all methods can be distinguished by their argument types, for example, the various $ implementations share the same name with different arguments: \ \ {{{ \ @see $(String) \ @see $(String, Element|jQuery) \ @see $(Element|Array<Element>) \ @see $(Function) \ }}} \ \ Those identifies must be converted to the hash identifies that the Mediawiki generates: \ \ {{{ \ #.24.28_html_.29 \ #.24.28_expr.2C_context_.29 \ #.24.28_fn_.29 \ #.24.28_elems_.29 \ }}} \ \ Currently the wiki uses the argument names to identify methods, I'd prefer that to be changed to argument types. \ \ It has to be considered to mix both, though I see the drawback here of increased effort to write and maintain the @see tags, while it may be easier to understand for the reader what is expected. |
|---|---|
| need: | → Review |
| resolution: | → invalid |
| status: | new → closed |
We don't use inline JSDoc any more.