Add @category tag

[wbhob]

Sometimes globally-scoped things can get pretty cluttered, so I was wondering if you all can add a @category tag to sort documented objects into groups.

[jonchardy]

I actually did this as part of our TypeDoc implementation. If you're curious, see jonchardy@c12381b. Alongside these changes, I updated our theme to sort our index page by category. There is some stuff specific to us like the weights for sorting, but you can change that up.

Excuse the organization, I usually push things to GitHub in batches.

The relevant changes are:
jonchardy@c12381b#diff-0d149f9b1469c3c2f367a941af1b0945
jonchardy@c12381b#diff-bd337a93cb6b55ec5c687ea8a327720e
jonchardy@c12381b#diff-739b66d6abaf9c587a31ae9909a64903
jonchardy@c12381b#diff-ebc8b0bc65bb184ea94b7734503a15f3
jonchardy@c12381b#diff-09c50b8d3de6159296d213ab8664a22a
jonchardy@c12381b#diff-431f5355945bc08849278b194d39a0df

[wbhob]

Pr? @jonchardy

[jonchardy]

Created PR #566. Feel free to take a look, discuss, and make any changes you feel will improve it.

[aciccarello]

Closed by #566

[emmanueltouzery]

Regarding closing this bug: I didn't try the changes yet, but my understanding is that the PR which was pulled, according to its author "won't really do much without some accompanying changes to a theme". So I'm not sure this feature is really complete now. Is changing the theme documented?

[aciccarello]

@emmanueltouzery I think you are right. I'll reopen this. PRs are welcome to update the themes.

[mootari]

I would also love to see multiple @category tags handled. The current implementation only keeps the first tag value around. Example:

    /**
     * @category Foo
     * @category Bar
     */

  "tags": [
    {
      "tag": "category",
      "text": "Foo"
    },
    {
      "tag": "category",
      "text": "Bar\n"
    }
  ]

becomes:

  "categories": [
    {
      "title": "Foo",
      "children": [
        371
      ]
    }
  ]

[mootari]

On a related note: I don't think it's a good idea to reformat the original category name. If need be this can be handled in the theme.

typedoc/src/lib/converter/plugins/CategoryPlugin.ts

Lines 123 to 128 in 32bf528

	for (let i = 0; i < tags.length; i++) {
	if (tags[i].tagName === 'category') {
	let tag = tags[i].text;
	return (tag.charAt(0).toUpperCase() + tag.slice(1).toLowerCase()).trim();
	}
	}

[Gerrit0]

I opened #1158 to track multiple categories, closing this as there is base functionality for categories already, and the themes have been updated.