Add a JsDoc 3 annotations and docs pipeline to TMH
Closed, ResolvedPublic
Actions

Assigned To

Authored By

	TheDJ
	Jun 8 2023, 1:16 PM

Description

Setup the TMH project to produce JSDoc documentation and add additional annotations to the various JS classes where required.

Details

Subject	Repo	Branch	Lines +/-
Re-enable jsdoc pedantic	mediawiki/extensions/TimedMediaHandler	master	+1 -1
Build: fix jsdoc warning	mediawiki/extensions/TimedMediaHandler	master	+3 -3
JSDoc for TMH modules	mediawiki/extensions/TimedMediaHandler	master	+800 -102
Unbreak TMH video initialization	mediawiki/extensions/TimedMediaHandler	master	+1 -1
Unset pedantic JSDoc for now	mediawiki/extensions/TimedMediaHandler	master	+1 -1
Add TimedMediaHandler to docroot	integration/docroot	master	+7 -0
Publish JS documentation for TimedMediaHandler	integration/config	master	+1 -0

Customize query in gerrit

Related Objects

Mentioned In: T284766: Document process to add jsdoc to a repository
T340816: Unable to load media player on mobile devices

Event Timeline

TheDJ created this task.Jun 8 2023, 1:16 PM

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJun 8 2023, 1:16 PM

JSDoc is terrible (especially wrt to name spacing and linking to external code)

I might look into how it does with some other templates that are well regarded like:
https://github.com/clenemt/docdash
https://github.com/contentful/contentful-sdk-jsdoc

Change 928988 had a related patch set uploaded (by TheDJ; author: TheDJ):

[mediawiki/extensions/TimedMediaHandler@master] Attempt at JSDoc for TMH modules

https://gerrit.wikimedia.org/r/928988

gerritbot added a project: Patch-For-Review.Jun 10 2023, 3:42 PM

TheDJ moved this task from Backlog to Active on the VideoJS player board.Jun 13 2023, 11:35 AM

Change 928988 merged by jenkins-bot:

[mediawiki/extensions/TimedMediaHandler@master] JSDoc for TMH modules

https://gerrit.wikimedia.org/r/928988

Maintenance_bot removed a project: Patch-For-Review.Jun 16 2023, 10:10 PM

Change 931319 had a related patch set uploaded (by TheDJ; author: TheDJ):

[integration/config@master] Publish JS documentation for TimedMediaHandler

https://gerrit.wikimedia.org/r/931319

Change 931320 had a related patch set uploaded (by TheDJ; author: TheDJ):

[integration/docroot@master] Add TMH to docroot

https://gerrit.wikimedia.org/r/931320

Change 931319 merged by jenkins-bot:

[integration/config@master] Publish JS documentation for TimedMediaHandler

https://gerrit.wikimedia.org/r/931319

Mentioned in SAL (#wikimedia-releng) [2023-06-20T05:06:13Z] <hashar> Reloaded Zuul for https://gerrit.wikimedia.org/r/c/integration/config/+/931319 # T338458

I have picked up the last merged change which was https://gerrit.wikimedia.org/r/c/mediawiki/extensions/TimedMediaHandler/+/871908 then manually triggered a postmerge build using:

ssh contint.wikimedia.org \
   zuul enqueue --trigger gerrit --pipeline postmerge --project mediawiki/extensions/TimedMediaHandler --change 871908,3

The build failed at https://integration.wikimedia.org/ci/job/mwext-node16-docs-docker-publish/2303/console

00:01:23.857 + npm run-script doc
00:01:24.134 
00:01:24.134 > doc
00:01:24.134 > jsdoc -c jsdoc.json
00:01:24.134 
00:01:26.470 WARNING: Unknown link Object.<string, Array.<SourceObject>> in Global
00:01:26.471 WARNING: Unknown link Object.<string, Array.<SourceObject>> in Global
00:01:26.471 WARNING: Unknown link Object.<string, Array.<SourceObject>> in Global
00:01:26.881 Build step 'Execute shell' marked build as failure

Warnings fail the jsdoc process ? That doesnt seem right…. well have to look into that i guess

Maybe because of:

jsdoc.json

{
  "opts": {
    "pedantic": true,
    ...
}

From https://jsdoc.app/about-commandline.html

--pedantic
Treat errors as fatal errors, and treat warnings as errors. Defaults to false.

Which looks a good practice :]

Change 931320 merged by jenkins-bot:

[integration/docroot@master] Add TimedMediaHandler to docroot

https://gerrit.wikimedia.org/r/931320

Mentioned in SAL (#wikimedia-operations) [2023-06-21T06:40:28Z] <hashar@deploy1002> Started deploy [integration/docroot@51d2552]: Add TimedMediaHandler to docroot - T338458

Mentioned in SAL (#wikimedia-operations) [2023-06-21T06:40:39Z] <hashar@deploy1002> Finished deploy [integration/docroot@51d2552]: Add TimedMediaHandler to docroot - T338458 (duration: 00m 11s)