jQuery: The Write Less, Do More JavaScript Library

Ticket #791 (new enhancement)

Opened 2 years ago

Last modified 9 months ago

Cross-reference API documentation

Reported by: joern Assigned to: anonymous
Type: enhancement Priority: major
Milestone: Component: docs
Version: Keywords:
Cc: Needs:

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

Note: See TracTickets for help on using tickets.