errors from closure-library & can't exclude closure-library

[myphysicslab]

Getting errors from closure-library when building docs with Dossier, but I don't know how to fix the errors. I'm able to build my docs, these are all warnings, but it is distracting to have so many warnings (which can obscure warnings I might care about).

There are two classes of errors.

1. Around 30 "Ignoring undeclared namespace" errors (see below). These I don't know where to start on solving (though they seem to be mostly from goog.testing).
2. Around a dozen "Discarded tag" warnings from com.github.jsdossier.soy.HtmlSanitizer.

For the "Discard tag" warnings, I've tried using @code tags, but then closure-compiler complains about the @code tag with

  WARNING - Parse error. illegal use of unknown JSDoc tag "code"; ignoring it

Perhaps using --extra_annotation_name option (whitelist of tag names in JSDoc) with closure-compiler would solve that, but I don't know how to add this to Dossier. These warnings seem to all be from the docs for goog.html.TrustedResourceUrl.format.

I've been unable to exclude documenting closure-library files. However I am able to exclude other files. I've tried using the excludes option in config.json without success. Here is my config.json:

{
    "output": "docs",
    "sources": [
        "src/lab/",
        "src/sims/",
        "src/test/"
    ],
    "closureLibraryDir": "closure-library/closure/goog",
    "readme": "src/docs/doc_start.md",
    "useMarkdown": "true",
    "typeFilters": [
        ".*\.i18n",
        "myphysicslab.lab.util.Terminal.regexPair"
    ],
    "excludes": [
        "closure-library/closure/goog/html",
        "closure-library/closure/goog/testing",
        "src/lab/engine2D/test",
        "src/lab/graph/test",
        "src/lab/model/test",
        "src/lab/util/test",
        "src/lab/view/test",
        "src/sims/pendulum/test",
        "src/sims/springs/test"
    ]
}

I've tried other variations like "closure-library" or "closure-library/closure/goog" or "closure-library/closure/goog/*" or "closure/goog" without success. Note that closure-library is a symbolic link in the directory where I am building. With my directory set to where I am building the docs I am able to list the closure-library files, for example:

[13:46:29 ~/Documents/Programming/myphysicslab]$ ls closure-library/closure/goog/html
flash.js            safescript_test.html        silverlight_test.html
flash_test.html         safescript_test.js      silverlight_test.js
flash_test.js           safestyle.js            testing.js
legacyconversions.js        safestyle_test.html     trustedresourceurl.js
legacyconversions_test.html safestyle_test.js       trustedresourceurl_test.html
legacyconversions_test.js   safestylesheet.js       trustedresourceurl_test.js
safehtml.js         safestylesheet_test.html    uncheckedconversions.js
safehtml_test.html      safestylesheet_test.js      uncheckedconversions_test.html
safehtml_test.js        safeurl.js          uncheckedconversions_test.js
safehtmlformatter.js        safeurl_test.html       utils.js
safehtmlformatter_test.html safeurl_test.js         utils_test.html
safehtmlformatter_test.js   sanitizer           utils_test.js
safescript.js           silverlight.js

Here are all of the first type of error and a sample of the second type.

Ignoring undeclared namespace DOUBLE_EQUALITY_PREDICATE
Ignoring undeclared namespace TO_STRING_EQUALITY_PREDICATE
Ignoring undeclared namespace PRIMITIVE_EQUALITY_PREDICATES
Ignoring undeclared namespace _trueTypeOf
Ignoring undeclared namespace _displayStringForValue
Ignoring undeclared namespace fail
Ignoring undeclared namespace argumentsIncludeComments
Ignoring undeclared namespace commentArg
Ignoring undeclared namespace nonCommentArg
Ignoring undeclared namespace _validateArguments
Ignoring undeclared namespace _getCurrentTestCase
Ignoring undeclared namespace _assert
Ignoring undeclared namespace assert
Ignoring undeclared namespace assertThrows
Ignoring undeclared namespace assertNotThrows
Ignoring undeclared namespace assertThrowsJsUnitException
Ignoring undeclared namespace assertTrue
Ignoring undeclared namespace assertFalse
Ignoring undeclared namespace assertEquals
Ignoring undeclared namespace assertNotEquals
Ignoring undeclared namespace assertNull
Ignoring undeclared namespace assertNotNull
Ignoring undeclared namespace assertUndefined
Ignoring undeclared namespace assertNotUndefined
Ignoring undeclared namespace assertNotNullNorUndefined
Ignoring undeclared namespace assertNonEmptyString
Ignoring undeclared namespace assertNaN
Ignoring undeclared namespace assertNotNaN
Ignoring undeclared namespace assertObjectEquals
Ignoring undeclared namespace assertObjectRoughlyEquals
Ignoring undeclared namespace assertObjectNotEquals
Ignoring undeclared namespace assertArrayEquals
Ignoring undeclared namespace assertElementsEquals
Ignoring undeclared namespace assertElementsRoughlyEqual
Ignoring undeclared namespace assertSameElements
Ignoring undeclared namespace assertEvaluatesToTrue
Ignoring undeclared namespace assertEvaluatesToFalse
Ignoring undeclared namespace assertHTMLEquals
Ignoring undeclared namespace assertCSSValueEquals
Ignoring undeclared namespace assertHashEquals
Ignoring undeclared namespace assertRoughlyEquals
Ignoring undeclared namespace assertContains
Ignoring undeclared namespace assertNotContains
Ignoring undeclared namespace assertRegExp
Ignoring undeclared namespace standardizeHTML
Ignoring undeclared namespace standardizeCSSValue
Ignoring undeclared namespace testRoller1

Sample of the second type of error:

[WARNING][com.github.jsdossier.soy.HtmlSanitizer] Discarded tag "label" in text:
<p>Creates a TrustedResourceUrl from a format string and arguments.</p>
<p>The arguments for interpolation into the format string map labels to values.
Values of type goog.string.Const are interpolated without modifcation.
Values of other types are cast to string and encoded with
encodeURIComponent.</p>
<p>%{<label>} markers are used in the format string to indicate locations
to be interpolated with the valued mapped to the given label. <label>
must contain only alphanumeric and '_' characters.</p>
<p>The format string must start with one of the following:</p>
<ul>
<li>https://<origin>/<pathStart></li>
<li>//<origin>/<pathStart></li>
<li>/<pathStart></li>
</ul>
<p><origin> must contain only alphanumeric, '-', .', ':', '[', and ']'.
<pathStart> must contain only alphanumeric, '_', '~', and '-'. If other
characters follow it, it must end with '/', '#' or '?'.</p>
<p>Example usage:
var url = goog.html.TrustedResourceUrl.format(goog.string.Const.from(
'https://www.google.com/search?q=%{query}), {query: searchTerm});</p>
<p>var url = goog.html.TrustedResourceUrl.format(goog.string.Const.from(
'//www.youtube.com/v/%{videoId}?hl=en&amp;fs=1%{autoplay}'), {
'videoId': videoId,
'autoplay': opt_autoplay ?
goog.string.Const.EMPTY : goog.string.Const.from('autoplay=1')
});</p>
<p>While this function can be used to create a TrustedResourceUrl from only
constants, fromConstant() and fromConstants() are generally preferable for
that purpose.</p>

In case it is helpful: all of my source code is now online and fairly easy to build. See https://github.com/myphysicslab/myphysicslab.

[jleyba]

re: exclusions, there's likely a bug where using closureLibraryDir ignores the exclusion list. I'll take a look.

re: HtmlSanitizer, these warnings are caused by poorly formatted jsdoc comments. For example:

/**
 * Create a <div> tag
 */

In that comment, <div> is parsed as raw HTML. If the raw HTML includes things HtmlSanitizer doesn't like (e.g. <label> in your example), it will scrub them out. You can either fix them by adding back-ticks to create an inline code block:

/**
 * Create a `<div>` tag
 */

Or use {@code } (as you would in javadoc):

/**
 * Create a {@code <div>} tag
 */

[myphysicslab]

Thanks, both the backticks and the {@code } are working. (I didn't realize backtick is an option, and I was incorrectly using @code{ } instead of {@code }).

It looks like the "Ignoring undeclared namespace" errors happen because there are lots of globals being defined in goog.testing without any type information. So being able to exclude at least that directory would probably be the best way to deal with it.