Filled out remaining tags documentation.

[mathematicalcoffee]

I've filled out the tags documentation for all the remaining JSDoc tags except:

• tags-lends (already done in Normalized line endings across all articles and ported @lends documentation #12)
• tags-ignore (ditto Implemented @ignore #13)
• tags-license (ditto Implemented @ignore #13)

I accidentally did tags-inner (also done in #13) and committed it (3fe4ebe) so I've left it in for now. Feel free to write over it with the changes from #13.

I think the only clashes with #13 will be tags-inner (as already mentioned), index.html (which can just be regenerated).

But there are probably quite a few clashes with #12 due to the line endings - might make sense for #12 to be merged before this one. (This will probably screw around with all the line ending settings though - all files have retained their original line endings, and files that I have created have Linux line endings).

Also, for now I have not made a page for @Undocumented. I'm torn between adding it for completeness (with a caveat "this is for use internally by JSDoc, you should use @ignore instead"), and leaving it out since just JSDoc uses it internally. I lean towards the former because I could imagine someone seeing the tag definition in the JSDoc source and wondering what it does. I have the tags-undocumented page prepared and can commit it to this branch if you agree.

[mathematicalcoffee]

I had a few questions while I was writing up:

• I noticed that in dictionary.js the @namespace and @module tags have canHaveType set to true - does this mean a namespace can have a type? what does "@namespace {number}" mean??
• there are a few tests about quoted names (test/specs/documentation/quotename.js) which suggest that you can use quotes to escape a name? Is that worth writing up/could I have a little more info on it? (e.g. chat."#chanel".open, even contacts."say-\"hello\"@example.com"?

[micmath]

I don't see why a namespace shouldn't be allowed to have a type.

/**
  @namespace {Number} one
 */
var one = new Number(1);

/**
  @method one.add
 */
one.add = function (n) { return n + 1; }

A more likely usage is a function that also acts like a namespace. These are popularly given names which look like punctuation or currency in my experience.

[micmath]

Yes, the quotes can be used when a namepath has stringy bits. Like

window["!"] = function (msg) { alert(msg); }
window["!"]("Code Red!");

This feature was specifically asked for in version 2. Specifically by whom, I cannot recall.

[mathematicalcoffee]

Great, I'll add these examples to the docs and add a couple more commits.

Can you give an example of the "more likely usage" of a namespace being a function? (I have absolutely no experience with JS when it has to do with the web - I come from a GNOME JS background - so am not really sure what this means). Do you mean something like $('html').variousFunctionsHere? So would I do /** @namespace {function} $ */ and then document properties of $?

The quote feature seems straightforward enough, I'll add a note to it on the @name page and possibly the @link/namepaths page.

[danielellis]

I find myself referencing this pull request more than the current tags documentation! Any timeline on when this will get merged?

[hegemonic]

@danielellis: Very soon. Doc updates are next on my list.

[hegemonic]

I've made a lot of headway on the review. Should be able to merge this (at last!!) next weekend, if not sooner.

[danielellis]

👍 You da man

[hegemonic]

This has finally been merged. @mathematicalcoffee, thanks once again for your heroic effort! The JSDoc community will benefit tremendously from all of your hard work.

I made a bunch of edits before I merged the changes, mostly for clarity and brevity. I also made some of the examples more concrete and removed some of the examples that focus on edge cases.

In addition, I did a bit of editing for consistency in terms of where we use <code> tags and so forth, and I tried to standardize on the following format for multiline block comments:

/**
 * This is a JSDoc comment.
 * @class
 */
function MyClass() {}

I also made a very small number of corrections; for example, it appears to me that the parser ignores the @this tag, so I updated the docs for @this accordingly.

@mathematicalcoffee, if you have questions or concerns about any of my edits, please feel free to email me directly or file new issues.