Feature Request: Make tag sorting optional

[unicornware]

Description

I'm attempting to integrate this plugin into my workflow, but I'm finding that the plugin automatically sorts jsdoc tags.

I already take the time to order my tags exactly the way I want them, so I do not want the plugin altering my order.

Example

/**
 * @file Katas - tribonacci
 * @module katas/tribonacci
 */

/**
 * Given a starting sequence, `[a, b, c]`, the function returns an array with
 * the first `n` elements of the sequence.
 *
 * @see https://codewars.com/kata/556deca17c58da83c00002db
 *
 * @example tribonacci([1, 1, 1], 10) => [1, 1, 1, 3, 5, 9, 17, 31, 57, 105]
 * @example tribonacci([0, 0, 1], 10) => [0, 0, 1, 1, 2, 4, 7, 13, 24, 44]
 *
 * @param {[number, number, number]} args - Starting sequence
 * @param {number} n - Total number of elements in sequence
 * @return {number[]} First `n` elements of sequence
 */
const tribonacci = (
  [a, b, c]: [number, number, number],
  n: number
): number[] => {
  // Base case: If n is less than or equal to zero, return empty array
  if (n <= 0) return []

  /** @const {number} sum - Sum of {@link a}, {@link b}, and {@link c} */
  const sum: number = a + b + c

  // Generate and return sequence
  return [a, ...tribonacci([b, c, sum], n - 1)]
}

export default tribonacci

becomes

/**
 * @module katas/tribonacci
 * @file Katas - tribonacci
 */

/**
 * Given a starting sequence, `[a, b, c]`, the function returns an array with
 * the first `n` elements of the sequence.
 *
 * @example
 *   tribonacci([1, 1, 1], 10) => [1, 1, 1, 3, 5, 9, 17, 31, 57, 105]
 *
 * @example
 *   tribonacci([0, 0, 1], 10) => [0, 0, 1, 1, 2, 4, 7, 13, 24, 44]
 *
 * @param {[number, number, number]} args - Starting sequence
 * @param {number} n - Total number of elements in sequence
 * @return {number[]} First `n` elements of sequence
 * @see https://codewars.com/kata/556deca17c58da83c00002db
 */
const tribonacci = (
  [a, b, c]: [number, number, number],
  n: number
): number[] => {
  // Base case: If n is less than or equal to zero, return empty array
  if (n <= 0) return []

  /** @const {number} sum - Sum of {@link a}, {@link b}, and {@link c} */
  const sum: number = a + b + c

  // Generate and return sequence
  return [a, ...tribonacci([b, c, sum], n - 1)]
}

export default tribonacci

The plugin has dramatically changed the ordering of my tags (and even threw in some unwanted formatting with my @example tags).

Additional Context

• Tag sorting isn't mentioned anywhere in the README
• I'd be happy to tackle this feature, but my coding style is much different than the repo 😅

[hosseinmd]

We should add it to options, but I don't know how, because there are many tags, maybe developer doesn't want to add all of them to options

[hosseinmd]

I like to make a built-in standard sort, I don't find anything about that, but this is for javadoc https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#orderoftags

[hosseinmd]

This is an example of phpDoc https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#1-functions-class-methods

[Inviz]

Yes i'm having issues with examples being sorted before param

[navishachiku]

Strongly recommend this feature.

If customizing the TAGS_ORDER is very complicated, then at least can set a switch to decide enable the plugin to sort automatically.

---

Or another inspiration, maybe can use default and override weights to sort?

e.g.

Default:

const DEFAULT_TAGS_ORDER = {
     REMARKS: 100,
     PRIVATE_REMARKS: 200,
     PROVIDES_MODULE: 300,
     MODULE: 400,
     ...
}

Customize (From plugin options)

const CUSTOMIZE_TAGS_ORDER = {
    PROVIDES_MODULE: 301
}

Then merge these two

const TAGS_ORDER = {
     REMARKS: 100,
     PROVIDES_MODULE: 300,
     PRIVATE_REMARKS: 301,
     MODULE: 400,
     ...
}

Adjust getTagOrderWeight

function getTagOrderWeight(tag, options) {
     if (tag === DESCRIPTION && !options.jsdocDescriptionTag) {
         return -1;
     }
     const index = TAGS_ORDER[tag] ?? -1;
     return index === -1 ? TAGS_ORDER['other'] : index;
}

But the disadvantage is that all weight values ​​must be listed on the description page for developers to view, which will make the description page a lot of content.

[hosseinmd]

jsdocTagsOrder added to options

[hosseinmd]

Released v1.3.0