Invalid JsDoc - @public

[Steven Hall]

After getting back some errors telling me that @public was not a valid
JsDoc annotation, I did some investigating into the causes.

I found that the STANDARD_DOC set in statetracker.py seemed to only
contain the JsDoc annotations defined in the Google Style Guide.

This is fine and I'd imagine it to be so, as this is a Closure tool.
However, it's clearly stated in the style guide that
"We [Google] use JSDoc comments to document files, classes,
methods and properties."

It's a bit misleading that, despite Google supporting JsDoc, they only
use a subset of the tags. Similarly, the @protected tag doesn't seem
to exist in the JsDoc documentation (found here
http://code.google.com/p/jsdoc-toolkit/wiki/TagReference).

Could we receive some clarification on whether Google uses full JsDoc
documentation, or a subset of it? And if full JsDoc is supported,
would it be possible to issue a fix so that the Linter reflects this?

Thanks

[Steven Hall]

Just thought I'd expand on this as it is a bit misleading and my
initial post was probably a bit abrupt.

@public and tags such as this are defined as being "discouraged" in
the Google style guide, which is fine.

I'm just having a bit of trouble making the distinction between
"discouraged" and actually breaking the style rules (as the Linter's
error logs would suggest). I understand that using @public would cause
an error in the Google Linter because you wouldn't expect to see
Google code with these tags in them.

However other applications may use these tags, which is fine (they're
JsDoc after all!), but the Linter would throw an error.

I think it might be a nice feature to include Google's set of approved
tags under the 'strict' flag, and let the full range of JsDoc tags be
allowed when strict is not set. This way those who use the Linter and
also use the full range of JsDoc annotations reap the benefits whereas
Google's internal code (which I am sure uses the strict flag)
maintains the restricted set of tags.

On Sep 2, 1:36 pm, Steven Hall <stvh...@gmail.com> wrote:
> After getting back some errors telling me that @public was not a valid
> JsDoc annotation, I did some investigating into the causes.
>
> I found that the STANDARD_DOC set in statetracker.py seemed to only
> contain the JsDoc annotations defined in the Google Style Guide.
>
> This is fine and I'd imagine it to be so, as this is a Closure tool.
> However, it's clearly stated in the style guide that
>     "We [Google] use JSDoc comments to document files, classes,
> methods and properties."
>
> It's a bit misleading that, despite Google supporting JsDoc, they only
> use a subset of the tags. Similarly, the @protected tag doesn't seem

> to exist in the JsDoc documentation (found herehttp://code.google.com/p/jsdoc-toolkit/wiki/TagReference).

[Andy Perelson]

The official policy for the Closure Linter is that we will allow only the jsdoc tags that are in the Google JavaScript Style Guide. Internally if we get a request for a new tag to be supported, we generally ask that it be added to the style guide first. In practice, we will also allow any tag that is explicitly supported by the Closure Compiler.

As for our use of JsDoc... we've certainly deviated from the JsDoc toolkit and today don't by default support using all the tags of the JsDoc toolkit. It's certainly at our discretion to not use certain tags if we don't want to, and in the case of our style guide... discouraged is strong enough that we don't allow discouraged tags by default (though there are workarounds I'll talk about later). As for tags that we've added like @protected, they are generally there to work in conjunction with our other tools like the Closure Compiler which uses those annotations as part of its own system of checks.

As for as putting all JsDoc toolkit tags in non-strict mode, I doubt we would do that by default. The default mode of the Closure Linter is supposed to enforce the Google style guide, which includes not using some of those tags, and strict mode is actually meant to enforce the more stringent and less openly defined Closure style.

That said there is already a solution to your problem. We have a --custom_jsdoc_tags flag that takes a list of comma separated tags that should be allowed. Using this flag you can add any flags you want, including @public and other official JsDoc tags. It also might be a good idea to add a flag or some other means of easily adding support (and in an ideal case even good checking of) all the JsDoc toolkit tags in one go. Feel free to file a feature request to track this issue if you'd like it.

Thank you,

Andy

[Steven Hall]

That's the kind of flag I was looking for. Thanks.