[docs] More specific types in YUIDoc

[fal-works]

How would this new feature help increase access to p5.js?

Not really a feature, but I'm wondering if we could describe more specific types in the YUIDoc comments (please see below, I'll be happy to work on it) in order to improve the machine-readable documentation.

This will help p5.ts to resolve some issues and generate better type definitions, which will also help those who love p5 but feel a little difficulty with dynamic-typed languages (e.g. who learned Processing Java first).
It might also open up other possibilities (if any exists -- at least I'm interested in a Haxe port as well).

Most appropriate sub-area of p5.js?

• Accessibility (Web Accessibility)
• Build tools and processes - might or might not affect the build process of the reference?
• Other (specify if possible) - documentation

Feature enhancement details:

Below I listed some points that could be improved.

I suppose the first two are relatively reasonable (however they'll require to edit the contributor docs as well), and of course I don't intend to change everything at once, but I'd like to ask if anyone has any concerns, or if there are any related issues.

What we can do relatively easily:

{Object} types

In some cases these can be simply replaced with existing types.

For instance,

/**
 * @method mousePressed
 * @param {Object} [event]  optional MouseEvent callback argument.
 * ...
 */

Here {Object} can be described more specifically: {MouseEvent}.

{Array} types

In many cases we can describe what kind of Array.

For instance,

/**
 * @method int
 * @param {String|Boolean|Number} n  value to parse
 * ...
 */
/**
 * @method int
 * @param {Array} ns  values to parse
 * ...
 */

Here {Array} can be described more specifically: {Array<String|Boolean|Number>}.

(By the way this case seems not to change the reference rendering;
we might need some conventions for choosing from either Array<SomeType> or SomeType[])

What will need a little more thoughts:

• Generic functions
  For instance in random(choices), the return type depends on the argument type.
• Generic class
  The actual type of p5.Element.elt depends on the case, e.g. createDiv().elt is HTMLDivElement
  (but as the first step it would also be fine to use always HTMLElement, which is a super-type).
• Callbacks
  May require some invention: Callback tag/type yui/yuidoc#33, Remove parentheses from YUIDoc params? #2042
• Properties of {Object}
  Maybe just in a few cases, such as in saveFrames().
• Variadic arguments
  Maybe just in a few cases, such as print(...args).

[fal-works]

I realized that I'm not 100% sure that the common syntax Array<SomeType> is valid in YUIDoc (although it passes the YUIDoc linter), while SomeType[] seems to be OK (from yui/yuidoc#198)

[limzykenneth]

YUIDoc is no longer being maintained and I'm a bit wary of continue relying on it going forward. However there isn't a good alternative out there that we can easily transition over to. I have started some exploration into a custom documentation generator based on the idea of YUIDoc but didn't have the time to make it feature complete for p5.js, it is working for my own project though.

[fal-works]

I understand, thought about that a bit too.
I guessed that the transition from YUIDoc will not be done in the near future, but indeed it's not ideal to invent some additional YUIDoc-specific technics.

I think this doesn't block replacing some of {Object}s and {Array}s as it can be done in a syntax that is common (almost if not all) to both JSDoc and YUIDoc, however other points I listed above may depend on the middle- or short-term plans about documantation generators.

By the way is there any reason to try a custom generator rather than JSDoc?
And what is the most difficult part of the transition? (migrating the build process of the reference I guess?)
I'm not very familiar with both JSDoc and YUIDoc, and I had the impression that JSDoc syntax is some kind of nearly upwardly compatible with YUIDoc (not by design but just as a result), which is maybe not correct.

[limzykenneth]

Two main problems with JSDoc for us:

1. It's heavily based around themes and static site generation whereas we already have a custom reference site setup how we want it and we can just plug in data in JSON form.
2. JSDoc puts requirement on the source code itself as it infers some information from the source code in addition to the code comments (YUIDoc doesn't do that because it is language agnostic, almost all JSDoc like JS documentation tool seems to do this). This will not work for p5.js for many reasons, one of the major one is that JSDoc won't be able to understand p5.js' global mode.

The difficulty lies only in generating a JSON file with the relevant data in it with the right structure, ideally we won't need to modify the actual reference page's code. The majority of the work is already done by comment-parser, and I have some tags already being handled, I've just yet to complete its compatibility with JSDoc/YUIDoc and spin it out as its own project. Though if something else out there fits our purpose without needed too much effort from the p5.js project itself, they can be considered as well.

[Qianqianye]

Closing this issue since it is addressed in #6972