From 97a5d335d78e78e793529233f5aac58440ff1155 Mon Sep 17 00:00:00 2001
From: Thiemo Kreuz <thiemo.kreuz@wikimedia.de>
Date: Thu, 24 Jan 2019 17:53:35 +0100
Subject: [PATCH] =?UTF-8?q?Replace=20rare=20{!=E2=80=A6}=20and=20{=3F?=
 =?UTF-8?q?=E2=80=A6}=20JSDoc=20syntax?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is documented at http://usejsdoc.org/tags-type.html, but not in many
other places, especially not in the JSDuck documentation.

The {!…} syntax means "can not be null". This is the default anyway.

The {?…} syntax means nullable. In a few situation is was used when a
parameter can be undefined. I decided to remove it everywhere and replace
it with {…|null} when appropriate, because this is much more explicit. Less
syntax to remember.

Note I'm intentionally not using the […] syntax when a parameter is followed
by non-optional parameters. Actually skipping a parameter in such a situation
would mess the parameter order up. Having optional parameters not at the end
is sometimes used as a feature in JavaScript code, but not in this codebase,
as far as I can see.

Change-Id: Ie370cfe08c32d1af5b0341951bed044fc3511c57
---
 resources/dist/index.js.map.json | Bin 190027 -> 190050 bytes
 src/preview/model.js             |  18 +++++++++---------
 src/reducers/preview.js          |   6 +++---
 tests/node-qunit/stubs.js        |   6 +++---
 4 files changed, 15 insertions(+), 15 deletions(-)

diff --git a/resources/dist/index.js.map.json b/resources/dist/index.js.map.json
index 8e008d3400fe0d215d8effdc6e0a065368f76cd5..6c3e95577c8af35ee63bcaf6fdbf0897d18f619e 100644
GIT binary patch
delta 155
zcmX?ohWpVO?hV$z_#KOi5-V#;^HNgNGV@YXHaq^}Wt{B)TYGc$Z)L`*t&GZ(!~gJ4
zpUT82INg306UXE`e<Y^oO=INP{Pzzp)8x269MdmwGICG;@LOm)zYL?&^sXL8vF5D*
z+q3>NF6*5Bp@oT!3t{?n@lGbC>FWd-Ii@%4W@4M}(a97rz0aMAefr_aOh(%;buv}P
F001w3Kbiml

delta 129
zcmaEKhWqpx?hV$z*z6sPiV`a~d;Q{NWVD|g{#%>Tesj}rWk#sP<eh)?f#NUzC;-Jd
z{)#d&Do&RDFD0#5TvC*omtLz-T9gx$r=X?aP?TCyT9l_yt=Js!e|x}x#tWV7_Wns(
csmUeN4LX^W7!{`nbuz^<DsJD<$+Rg304bR<<^TWy

diff --git a/src/preview/model.js b/src/preview/model.js
index da5584c1c..af817df77 100644
--- a/src/preview/model.js
+++ b/src/preview/model.js
@@ -29,12 +29,12 @@ export { previewTypes };
  * @property {string} url The canonical URL of the page being previewed
  * @property {string} languageCode
  * @property {string} languageDirection Either "ltr" or "rtl"
- * @property {?Array} extract `undefined` if the extract isn't
+ * @property {Array|undefined} extract `undefined` if the extract isn't
  *  viable, e.g. if it's empty after having ellipsis and parentheticals
  *  removed; this can be used to present default or error states
  * @property {string} type One of the previewTypes.TYPE_… constants.
- * @property {?Object|undefined} thumbnail
- * @property {?number|undefined} pageId
+ * @property {Object|undefined} thumbnail
+ * @property {number|undefined} pageId
  *
  * @global
  */
@@ -46,10 +46,10 @@ export { previewTypes };
  * @param {string} url The canonical URL of the page being previewed
  * @param {string} languageCode
  * @param {string} languageDirection Either "ltr" or "rtl"
- * @param {?Array} extract
+ * @param {Array|undefined|null} extract
  * @param {string} type
- * @param {?Object} [thumbnail]
- * @param {?number} [pageId]
+ * @param {Object} [thumbnail]
+ * @param {number} [pageId]
  * @return {PreviewModel}
  */
 export function createModel(
@@ -80,9 +80,9 @@ export function createModel(
 /**
  * Creates an empty preview model.
  *
- * @param {!string} title
- * @param {!string} url
- * @return {!PreviewModel}
+ * @param {string} title
+ * @param {string} url
+ * @return {PreviewModel}
  */
 export function createNullModel( title, url ) {
 	return createModel( title, url, '', '', [], '' );
diff --git a/src/reducers/preview.js b/src/reducers/preview.js
index b3a248c1b..6c58d0f5a 100644
--- a/src/reducers/preview.js
+++ b/src/reducers/preview.js
@@ -4,10 +4,10 @@ import nextState from './nextState';
 /**
  * Reducer for actions that modify the state of the preview model
  *
- * @param {?Object} state before action
- * @param {!Object} action Redux action that modified state.
+ * @param {Object|undefined} state before action
+ * @param {Object} action Redux action that modified state.
  *  Must have `type` property.
- * @return {!Object} state after action
+ * @return {Object} state after action
  */
 export default function preview( state, action ) {
 	if ( state === undefined ) {
diff --git a/tests/node-qunit/stubs.js b/tests/node-qunit/stubs.js
index 9b3ded0bc..ce1c22c29 100644
--- a/tests/node-qunit/stubs.js
+++ b/tests/node-qunit/stubs.js
@@ -55,10 +55,10 @@ export function createStubExperiments( bucket ) {
  * Creates a **minimal** stub that can be used in place of an instance of
  * `mw.Title`.
  *
- * @param {!number} namespace
- * @param {!string} prefixedDb, e.g. Foo, or File:Bar.jpg
+ * @param {number} namespace
+ * @param {string} prefixedDb, e.g. Foo, or File:Bar.jpg
  * @param {string|null} [fragment]
- * @return {!Object}
+ * @return {Object}
  */
 export function createStubTitle( namespace, prefixedDb, fragment = null ) {
 	return {