Improvements to tags pages once all the pull requests are merged.

[mathematicalcoffee]

While writing documentation for the tags pages, I made a list of things I think might make the pages nicer.

I'll summarise them here in a separate issue to all the pull requests that actually fill out the tag page content. The idea is that these could be resolved once all those other requests have been merged (i.e. only fix these once all the documentation is mostly in-place).

I'm happy to do all of these (in fact have started some already, waiting on those pull requests to be merged), but would like some extra opinions on these items (for example you might not agree with some of them, or have extra ones to add).

• put tag synonyms in the tag title? e.g. I will often search index.html for my tag of interest on index.html but if I search for @func I will find nothing as it is listed as @method. Propose setting the tag title to "@method, @func" or something like that.'
• currently all subsections in the tags pages (Syntax, Overview etc) are <h3>. Since the article title is rendered as h1 in the template, we should promote all h3s up to h2 (no point having a jump in heading levels).
  • while I'm at it, perhaps I should check all pages for this. For example, the about-jsdoce file has a h1 heading "JSDoc 3" up the top which duplicates its generated heading. Or about-license has two h1s which should probably be demoted to h2 to fit in with the heading hierarchy.
• Syntax section of tags (this is a bit nit-picky)
  • should all tag pages have a Syntax section? currently only those that have values have syntax sections (e.g. @name <namePath>. Those that have no values like @ignore have no syntax section). The supporting reason would be consistency.
  • Fix the style of the syntax section a little bit. The <code> tags look quite ugly to me, but beyond that, the syntax section of the page is flush to the left of the page while the headings are all indented a fair way. It looks a little off to me. Perhaps a {{#syntax}}{{/syntax}} similar to the current {{#example}} mustache template could be used. Even if it is not styled different to how it currently is, at least it allows us to say "let's change all syntax blocks to look like this" in the future.
• tag index (on index.html) should be alphabetical by tag name (pull request sort tag pages alphabetically by title on the index page #16 submitted)
• check for broken links in all pages (including tags pages) (I've fixed a few already in my fix-broken-links branch; will do another check once all the tag pages are merged)

(I will admit, I also did this because I just found out about Github's markdown task lists and wanted to try them out. squee!)

Anyhow, once all the other pull requests are merged, let me know which of these you'd like me to do.

[hegemonic]

Oh, boy, Markdown task lists! Here we go:

• Tag synonyms: Maybe we could do something like so: "@function (synonyms: @func, @method)" (Monospacing not necessary; just doing that to keep GitHub from auto-linking the tags.)

• Heading levels: I agree that the current heading levels are incorrect, and you are more than welcome to clean them up! (I'm also not losing any sleep over this, so if you'd rather spend your time elsewhere, fine by me.) Fixing the heading levels may necessitate some CSS changes.

• Syntax section: I'm not averse to including the syntax section on all pages; I agree that the extra clarity is worth the slight redundancy. As for styling, I'm not sure the Mustache helper is necessary--I think we could fix the issue you mentioned by adding a new CSS selector along these lines (note that I haven't tested this):

  h3 > code {
    text-indent: 2%;
  }

• Tag index: Yep, tags should definitely be alphabetical. I'll consider this handled by sort tag pages alphabetically by title on the index page #16.

• Broken links: Yep, we should fix 'em.

Thanks, @mathematicalcoffee!

[hegemonic]

Most of these issues were fixed by other recent changes. We still need to add a "Syntax" section for each tag, though.