Consistent order of jsdoc attributes

[trych]

Before I reapply new categories to the basil functions (see #264), I would like to make the order of attributes of the inline jsdoc documentation consistent. At the moment, it is somewhat mixed and inconsistent. Here is my suggestion of how the order and appearance should look:

/**
 * @description The description.
 * @method methodName
 * @cat Category
 * @subcat Subcategory, if any
 * @param  {parameterType} param Some parameter, if any.
 * @return {returnType} The return value, if any.
 *
 * @example <caption>Example of using the method, if any</caption>
 * myMethodCode();
 */

Some notes:

• As we need the @description tag a few times (for using inline html) I would suggest to use it all the time, to be consistent.
• Is it okay to always have the description in one line? I find it difficult to edit the descriptions with the manual line breaks.
• Should we leave the @method tag at @method or change it to @function (as we have functions now, not b-methods anymore)? p5.js has it at @method although they use functions.

Does this look okay? @fabianmoronzirfas If so, I would go ahead, and edit them all to be consistent.

[ff6347]

++ for @description all the time
+- for @description in several lines. Might reduce readability when user has no line-wrap enabled
-- for change of @method if not tested with output. I specifically use tags generated from documentation.js I can't tell if this introduces a breaking change. I will need to test this first.

[trych]

Might reduce readability when user has no line-wrap enabled
Yes, I find it just super annoying when you have to add a few words and then need to shift around the twenty following lines manually. Or is there some Sublime package that I am missing out on?
What do the other ones think on that point? @basiljs

@method will stay in place then, no problem.

@fabianmoronzirfas, is the order also alright? I mean I guess it does not make a difference for parsing at all, I just want a consistent order that reads well for the devs.

[ff6347]

The order is fine for me. You can toggle the soft wrap in st3. Is a build in setting

[trych]

@fabianmoronzirfas Could we turn on Markdown for JSDoc?

Once we do that we can could write inline code in the descriptions like this:

[...] my description containing a `code snippet` that is easy to type [...]

instead of the current:

[...] my description containing a <code>code snippet</code> that is harder to type [...]

And we could also have easier typing of links etc.

Or is this already turned on?

[ff6347]

We are not using jsdoc. We are using documentation.js. Don't ask me why I started with it. At that time it seemed like a good choice. Currently I'm not sure. Anyway. It might work to have markdown in there. I will have to test that. Let's create an issue for that.

[trych]

Fixed in #270. Closing this.