The code in .cacheTemplateDataApiResponse() where the `specCache`
is filled skips missing pages. .setTemplateData() is never called.
While we could – in theory – check the `missing` flag (as done in
patchset 1), this flag never makes it to the spec.
Rather simple solution: Mark everything as undocumented, as long
as .setTemplateData() is not called.
This affects only missing pages. .setTemplateData() is called in
all other situations.
Bug: T272487
Bug: T276574
Bug: T290136
Change-Id: I7045e84f2f2ba5aa4591c94ea495b0249e6c40d6
There are 2 situations:
1. Either the template name is used in a [[…]] link. In this case
we must provide the namespace. MWTemplateModel.getTitle() does
this. However, it's not a mw.Title object and therefor not really
guaranteed to be a valid title. This is fine. The worst thing
that can happen is that the link points to an error message.
But this should be entirely unreachable anyway.
2. Some messages want to display the name of the template.
Ideally without the namespace. That's what
MWTemplateSpecModel.getLabel() is for. Again this is not
guaranteed to be a valid mw.Title. But it doesn't need to. It's
only used as a label.
Change-Id: I03d0481201620a2f5c444ee32b656bcaade98aac
Notably:
* Include parameter aliases, labels and descriptions in the
search.
* Don't use a possibly outdated search index, but live data.
* Clear filter when a new checkbox is added.
Bug: T272481
Change-Id: Ie90a803af6178a8bb6de370a0f8e079800d9f8a2
Separation of concerns:
* The template model knows which parameters are currently used,
but doesn't know what's documented.
* The spec knows what's documented, but doesn't know what's
currently used.
Change-Id: I97cac00d6775a17a07059d0e8a7a116adc6080b3
If a known parameter is present using one of it's aliases, then
only the aliased name should be shown to the user. This patch,
therefore, resolves the issue of the same parameter being added
to the sidebar twice.
When adding a parameter that is aliased, it will receive the same
position as the non-aliased parameter it is replacing.
Bug: T274545
Change-Id: If4e58c941fd0f0e690d3603935f5a5d3f9938163
This also removes a few lines of text that don't explain
anything that would not be obvious from the code or @return
tag anyway.
Change-Id: I2f8f02dd61c50d9990d72c0e8ea79d679c9b11f2
This fixes a minor issue in the spec class. In the first step,
parameters from the template are added to the list of known
parameters. Later, aliases are resolved. The original behavior
was that such a parameter moved to the end of the list. This
is rather unexpected.
This dosn't have much of an impact. The pretty much only place
where the parameter order from the spec can be seen is in the
parameter search widget. Still I believe it's worth fixing.
Bug: T285483
Change-Id: I455818451811e92bba3e9320c2d41e1db8d563f2
I don't want this code to crash when the TemplateData API
returns an unexpected result.
Bug: T285483
Change-Id: I237cbfbb85892a53a08d9e7e34cf4974775d627a
This doesn't "extend". It was never used like this. What it
actually does is to link between a (cached) TemplateData blob
and the spec class that want's to use it.
Is this the best possible name?
* fillFromTemplateData( … )?
* propagateTemplateDocumentation( … )?
* readDocumentationFrom( templateData )?
* …?
Do we want to rename the "spec" class as well?
* MWTemplateDocumentation?
* MWTemplateMetadata?
* MWTemplateDataAccessor?
* …?
Bug: T285483
Change-Id: I6c52ef42d411c2f47fc0080768d36ebda4dd2a55
Just store the JSON blob from the TemplateData API as is.
This comes with a bunch of nice consequences:
* Less code.
* Less class properties that don't do anything but copy what's
in the TemplateData blob.
* Easier to understand what's going on. The `this.templateData`
property is now a reference to the *actual* TemplateData
documentation.
* No need to cache the documentedParamOrder. Just do it when
needed.
This also removes an unused feature from the `extend()` method
that didn't made sense anyway. Before it was possible to merge
conflicting documentations. But this is not only unused, it's
impossible to have multiple documentations for the same
template.
The method acts as a straight setter now. The next patch will
rename it accordingly.
Bug: T285483
Change-Id: I3ffc202577e9a20fc7491234601ccd981113f866
Instead of faking entries in this.params, let's use a separate
tiny data structure to keep track of parameters we have seen so
far, and in which order.
This finally allows to easily distinguish between documented and
undocumented parameters.
Bug: T285483
Change-Id: Idf62b0661178a3bbef7e817edf016dbd572d415b
The so called "spec" class keeps track of parameters that have
been used before, no matter if documented via TemplateData or
not. Removed parameters are still "known" (i.e. have been seen
before).
This feature allows to easily find previously used parameters
names when an undocumented parameter was removed and the user
tries to add it again.
Bug: T285483
Change-Id: Ia1555eea87cd99e7a3f386f4279ec5a80fb98a79
In I04b8a14fbec7be5a1c4defabf92e94f694c1e638 we sepearted params from
aliases. There we missed that re-filling the parameters from the
template could re-add the aliases.
Bug: T285483
Bug: T285843
Change-Id: I1928b443a5f708bc8c57efa5ad0a86b5915b159c
While the term "canonical" is not wrong, I find it still
somewhat ambiguous.
1. "Canonical" could mean different things. E.g. is the order
of parameters as they appear in the article's wikitext the
"canonical" one? It's possible to argue like this, esp. if a
template doesn't have TemplateData documentation. In this case
the only order known is the one from the wikitext.
2. "Canonical" sounds like the parameters must be reordered.
But this should never happen. Not having dirty diffs is more
important than having the parameters in a specific order.
Bug: T285483
Change-Id: I23658d37fea50b727667677ac6a49066673b2135
These comments don't add any knowledge. The text is either
duplicated, or the method signatur says it already. Having
to read these comments just to realize that they don't give
any additional information is not helpful, even error-prone.
Change-Id: I014028b1e9311b831a22c37859b2130aed2e9539
Wait, what's going on here? This patch looks like it changes the
behavior of this code. But it doesn't. Here is what happened
before:
* Let's say a template contains 2 parameters, A and B.
* We don't know yet if these names are aliases.
* getParameterNames() returns [ "A", "B" ].
* extend() is called. The TemplateData documentation contains
the parameters "B" and "C". "C" does have an alias "A".
* extend() can't find "C" and adds it to the end, as if it's a
new parameter.
* extend() also iterates the aliases. For each alias it creates
a reference to the specification object. In this case a
reference from "A" to "C" is created.
* But "A" already exists. The position of "A" doesn't change,
but the specification now says it's an alias.
* getParameterNames() skips aliases. It skips "A" and instead
returns the new "C" from the end of the list.
This was the behavior before. It's unchanged, proven by the tests.
Change-Id: I04b8a14fbec7be5a1c4defabf92e94f694c1e638
The idea is to not actually store all these default values, but
fall back to the default only when needed.
Some more details:
* The only remaining property is ….name. The only reason to
have this property is to distinguish between aliases and
primary parameter names. This will be reworked in a later
patch.
* The description falls back to null because this is the
documented fallback, not undefined.
* The default value falls back to "", same as the auto-value.
Why not null you might ask. This is intentional. Both the
auto- and default value are effectively wikitext snippets,
while the example is a label in the VE UI.
Bug: T285483
Change-Id: I1be3cca18f9ad6fc1c16362b24633f7613f02539
This is done for two reasons:
1. It fixes the behavior of two methods in rare edge-case
situations. They aren't documented to return undefined.
2. It reduces the amount of stuff this class stores when it's
nothing but a default value anyway. Note this patch does this
for the template-level properties only. Another patch will do
the same for the parameter-level properties.
Bug: T285483
Change-Id: If2e4d56da1fa52e32dc94191f36d7dc6a1487829
This reflects much better how this method is meant to behave.
Note I will continue to remove documentation that doesn't
explain anything in addition to what the code already says.
Bug: T285483
Change-Id: I81fa8a5d9d0752f3aeac4015c9a27b50e054d4df
This patch also marks 2 methods as @private that are not and
should not be used outside of this class.
Bug: T285483
Change-Id: I8a8ffc4868a369b5c47068beb0e83f023872543d
This reverts the revert commit d47b95eb4a.
When no `paramOrder` is given, known parameters should appear in the
order returned from the TemplateData API.
Previously, when TemplateData was present but no paramOrder
specified, then the parameters would appear in alphabetical order as
"unknown" parameters. Now they will appear in the order listed in
TemplateData. This is similar to the fully-specified behavior when
paramOrder is present.
This will only affect the Visual Editor template dialog, and has no
effect on serialization.
Bug: T274545
Change-Id: If8315781572af688ea1c1b14b3694b828f076b4a
This makes the code more readable and easier to reason about.
The ESLint rule responsible for this code style was removed
just recently.
Notes:
* I focus on classes that are relevant for what the WMDE team
does right now.
* I merge multiple `var` keywords only when the variables are
strongly connected.
* Caching the length in a for loop makes the code hard to
read, but not really faster when it's a trivial property
access anyway.
Bug: T284895
Change-Id: I621fed61d894a83dc95f58129bbe679d82b0f5f5
These don't add any knowledge but make the code harder to read
and maintain, and are an additional source of errors.
Change-Id: Ied57741a3f985e355adfddb4e75378d5c497faa9
The idea is to possibly rename some of these classes, based on
these descriptions. But this should be done in later, separate
patches.
Change-Id: I7f9e5b2382711b434d6dd618489fa3ed8b7a46b4
Returns true if there is no meaningful user input yet.
Will be used in the next patch.
Bug: T272355
Change-Id: I4f88ce31662bbc46755f78d574c46b907581d438
A @method annotation is only necessary when the docblock is not
directly followed by a function declaration (in which case JSDuck
assumes it documents a property), e.g. when defining an abstract
function or referencing a function from another library.
I verified that JSDuck generates exactly the same output before and
after this change (docs/data-<hash>.js files are identical).
Change-Id: I7edf51a8560ab9978b42800ab1026f0b5555c3bf
