Ticket #791 (closed enhancement: invalid)
Cross-reference API documentation
|Reported by:||joern||Owned by:|
Description (last modified by john) (diff)
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.