Replace ESDocs generated api-docs with api-documenter markdown (video-dev#5163)

Author: robwalch

.esdoc.json

@@ -8,6 +8,10 @@ on:
 
 permissions: {}
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   config:
     runs-on: ubuntu-latest
@@ -99,6 +103,8 @@ jobs:
         run: |
           npm run build:ci
           npm run docs
+          ./scripts/check-docs-built.sh
+
           # check that hls.js doesn't error if requiring in node
           # see https://github.com/video-dev/hls.js/pull/1642
           node -e 'require("./" + require("./package.json").main)'

.github/workflows/build.yml

@@ -21,6 +21,7 @@ coverage/
 /dist.zip
 /netlify
 /api-docs
+/api-docs-markdown
 
 # eslint
 .eslintcache

.gitignore

@@ -11,7 +11,8 @@
     "reportTempFolder": "<projectFolder>/api-extractor/report-temp"
   },
   "docModel": {
-    "enabled": false
+    "enabled": true,
+    "apiJsonFilePath": "<projectFolder>/api-extractor/<unscopedPackageName>.api.json"
   },
   "dtsRollup": {
     "enabled": true,

api-extractor.json

@@ -1 +1,3 @@
 /report-temp
+hls.js.api.json
+api-documenter

api-extractor/.gitignore

@@ -427,7 +427,7 @@ export interface ErrorData {
 
 // Warning: (ae-missing-release-tag) "ErrorDetails" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public
+// @public (undocumented)
 export enum ErrorDetails {
     // (undocumented)
     AUDIO_TRACK_LOAD_ERROR = "audioTrackLoadError",
@@ -515,7 +515,7 @@ export enum ErrorDetails {
 
 // Warning: (ae-missing-release-tag) "ErrorTypes" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public
+// @public (undocumented)
 export enum ErrorTypes {
     // (undocumented)
     KEY_SYSTEM_ERROR = "keySystemError",
@@ -531,7 +531,7 @@ export enum ErrorTypes {
 
 // Warning: (ae-missing-release-tag) "Events" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public
+// @public (undocumented)
 export enum Events {
     // (undocumented)
     AUDIO_TRACK_LOADED = "hlsAudioTrackLoaded",
@@ -751,7 +751,7 @@ export interface FragLoadingData {
 
 // Warning: (ae-missing-release-tag) "Fragment" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export class Fragment extends BaseSegment {
     constructor(type: PlaylistLevelType, baseurl: string);
     // (undocumented)
@@ -913,8 +913,6 @@ export type HdcpLevel = typeof HdcpLevels[number];
 // @public (undocumented)
 export const HdcpLevels: readonly ["NONE", "TYPE-0", "TYPE-1", "TYPE-2", null];
 
-// Warning: (ae-missing-release-tag) "Hls" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
 // @public
 class Hls implements HlsEventEmitter {
     constructor(userConfig?: Partial<HlsConfig>);
@@ -931,7 +929,6 @@ class Hls implements HlsEventEmitter {
     get capLevelToPlayerSize(): boolean;
     // Warning: (ae-setter-with-docs) The doc comment for the property "capLevelToPlayerSize" must appear on the getter, not the setter.
     set capLevelToPlayerSize(shouldStartCapping: boolean);
-    // (undocumented)
     readonly config: HlsConfig;
     // (undocumented)
     createController(ControllerClass: any, components: any): any;
@@ -946,15 +943,19 @@ class Hls implements HlsEventEmitter {
     get drift(): number | null;
     // (undocumented)
     emit<E extends keyof HlsListeners>(event: E, name: E, eventObject: Parameters<HlsListeners[E]>[1]): boolean;
+    // (undocumented)
     static get ErrorDetails(): typeof ErrorDetails;
+    // (undocumented)
     static get ErrorTypes(): typeof ErrorTypes;
+    // (undocumented)
     static get Events(): typeof Events;
     get firstLevel(): number;
     // Warning: (ae-setter-with-docs) The doc comment for the property "firstLevel" must appear on the getter, not the setter.
     set firstLevel(newLevel: number);
     get forceStartLoad(): boolean;
     static isSupported(): boolean;
     get latency(): number;
+    // (undocumented)
     get levels(): Level[];
     // (undocumented)
     listenerCount<E extends keyof HlsListeners>(event: E): number;
@@ -1017,7 +1018,6 @@ class Hls implements HlsEventEmitter {
     // (undocumented)
     trigger<E extends keyof HlsListeners>(event: E, eventObject: Parameters<HlsListeners[E]>[1]): boolean;
     get ttfbEstimate(): number;
-    // (undocumented)
     readonly userConfig: Partial<HlsConfig>;
     static get version(): string;
 }
@@ -1085,7 +1085,7 @@ export interface HlsEventEmitter {
 
 // Warning: (ae-missing-release-tag) "HlsListeners" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export interface HlsListeners {
     // (undocumented)
     [Events.AUDIO_TRACK_LOADED]: (event: Events.AUDIO_TRACK_LOADED, data: AudioTrackLoadedData) => void;
@@ -1429,7 +1429,7 @@ export type LevelControllerConfig = {
 
 // Warning: (ae-missing-release-tag) "LevelDetails" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export class LevelDetails {
     constructor(baseUrl: any);
     // (undocumented)
@@ -2049,7 +2049,7 @@ export interface NonNativeTextTracksData {
 
 // Warning: (ae-missing-release-tag) "Part" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
-// @public (undocumented)
+// @public
 export class Part extends BaseSegment {
     constructor(partAttrs: AttrList, frag: Fragment, baseurl: string, index: number, previous?: Part);
     // (undocumented)

api-extractor/report/hls.js.api.md

@@ -1,5 +1,7 @@
 # HLS.js v1 API
 
+See [API Reference](https://hls-js-dev.netlify.app/api-docs/) for a complete list of interfaces available in the hls.js package.
+
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
@@ -19,7 +21,7 @@
   - [`Hls.DefaultConfig get/set`](#hlsdefaultconfig-getset)
   - [`capLevelToPlayerSize`](#capleveltoplayersize)
   - [`capLevelOnFPSDrop`](#caplevelonfpsdrop)
-  - [`ignoreDevicePixelRatio`](#ignoreDevicePixelRatio)
+  - [`ignoreDevicePixelRatio`](#ignoredevicepixelratio)
   - [`debug`](#debug)
   - [`autoStartLoad`](#autostartload)
   - [`startPosition`](#startposition)
@@ -31,7 +33,7 @@
   - [`maxBufferHole`](#maxbufferhole)
   - [`maxStarvationDelay`](#maxstarvationdelay)
   - [`maxLoadingDelay`](#maxloadingdelay)
-  - [`lowBufferWatchdogPeriod`](#lowbufferwatchdogperiod) (deprecated)
+  - [`lowBufferWatchdogPeriod` (deprecated)](#lowbufferwatchdogperiod-deprecated)
   - [`highBufferWatchdogPeriod`](#highbufferwatchdogperiod)
   - [`nudgeOffset`](#nudgeoffset)
   - [`nudgeMaxRetry`](#nudgemaxretry)
@@ -41,9 +43,9 @@
   - [`liveMaxLatencyDurationCount`](#livemaxlatencydurationcount)
   - [`liveSyncDuration`](#livesyncduration)
   - [`liveMaxLatencyDuration`](#livemaxlatencyduration)
-  - [`maxLiveSyncPlaybackRate`](#maxLiveSyncPlaybackRate)
+  - [`maxLiveSyncPlaybackRate`](#maxlivesyncplaybackrate)
   - [`liveDurationInfinity`](#livedurationinfinity)
-  - [`liveBackBufferLength`](#livebackbufferlength) (deprecated)
+  - [`liveBackBufferLength` (deprecated)](#livebackbufferlength-deprecated)
   - [`enableWorker`](#enableworker)
   - [`enableSoftwareAES`](#enablesoftwareaes)
   - [`startLevel`](#startlevel)
@@ -52,19 +54,21 @@
   - [`fragLoadingMaxRetryTimeout` / `manifestLoadingMaxRetryTimeout` / `levelLoadingMaxRetryTimeout`](#fragloadingmaxretrytimeout--manifestloadingmaxretrytimeout--levelloadingmaxretrytimeout)
   - [`fragLoadingRetryDelay` / `manifestLoadingRetryDelay` / `levelLoadingRetryDelay`](#fragloadingretrydelay--manifestloadingretrydelay--levelloadingretrydelay)
   - [`startFragPrefetch`](#startfragprefetch)
-  - [`testBandwidth`](#testBandwidth)
-  - [`fpsDroppedMonitoringPeriod`](#fpsDroppedMonitoringPeriod)
-  - [`fpsDroppedMonitoringThreshold`](#fpsDroppedMonitoringThreshold)
+  - [`testBandwidth`](#testbandwidth)
+  - [`progressive`](#progressive)
+  - [`lowLatencyMode`](#lowlatencymode)
+  - [`fpsDroppedMonitoringPeriod`](#fpsdroppedmonitoringperiod)
+  - [`fpsDroppedMonitoringThreshold`](#fpsdroppedmonitoringthreshold)
   - [`appendErrorMaxRetry`](#appenderrormaxretry)
   - [`loader`](#loader)
   - [`fLoader`](#floader)
   - [`pLoader`](#ploader)
   - [`xhrSetup`](#xhrsetup)
   - [`fetchSetup`](#fetchsetup)
   - [`abrController`](#abrcontroller)
-  - [`bufferController`](#bufferController)
-  - [`capLevelController`](#capLevelController)
-  - [`fpsController`](#fpsController)
+  - [`bufferController`](#buffercontroller)
+  - [`capLevelController`](#caplevelcontroller)
+  - [`fpsController`](#fpscontroller)
   - [`timelineController`](#timelinecontroller)
   - [`enableDateRangeMetadataCues`](#enabledaterangemetadatacues)
   - [`enableEmsgMetadataCues`](#enableemsgmetadatacues)
@@ -76,11 +80,11 @@
   - [`captionsTextTrack1LanguageCode`](#captionstexttrack1languagecode)
   - [`captionsTextTrack2Label`](#captionstexttrack2label)
   - [`captionsTextTrack2LanguageCode`](#captionstexttrack2languagecode)
-  - [`captionsTextTrack3Label`](#captionsTextTrack3Label)
-  - [`captionsTextTrack3LanguageCode`](#captionsTextTrack3LanguageCode)
-  - [`captionsTextTrack4Label`](#captionsTextTrack4Label)
-  - [`captionsTextTrack4LanguageCode`](#captionsTextTrack4LanguageCode)
-  - [`renderTextTracksNatively`](#renderTextTracksNatively)
+  - [`captionsTextTrack3Label`](#captionstexttrack3label)
+  - [`captionsTextTrack3LanguageCode`](#captionstexttrack3languagecode)
+  - [`captionsTextTrack4Label`](#captionstexttrack4label)
+  - [`captionsTextTrack4LanguageCode`](#captionstexttrack4languagecode)
+  - [`renderTextTracksNatively`](#rendertexttracksnatively)
   - [`stretchShortVideoTrack`](#stretchshortvideotrack)
   - [`maxAudioFramesDrift`](#maxaudioframesdrift)
   - [`forceKeyFrameOnDiscontinuity`](#forcekeyframeondiscontinuity)
@@ -93,13 +97,14 @@
   - [`abrBandWidthUpFactor`](#abrbandwidthupfactor)
   - [`abrMaxWithRealBitrate`](#abrmaxwithrealbitrate)
   - [`minAutoBitrate`](#minautobitrate)
-  - [`emeEnabled`](#emeEnabled)
-  - [`widevineLicenseUrl`](#widevineLicenseUrl) (deprecated)
-  - [`licenseXhrSetup`](#licenseXhrSetup)
-  - [`licenseResponseCallback`](#licenseResponseCallback)
-  - [`drmSystems`](#drmSystems)
-  - [`drmSystemOptions`](#drmSystemOptions)
-  - [`requestMediaKeySystemAccessFunc`](#requestMediaKeySystemAccessFunc)
+  - [`emeEnabled`](#emeenabled)
+  - [`widevineLicenseUrl` (deprecated)](#widevinelicenseurl-deprecated)
+  - [`licenseXhrSetup`](#licensexhrsetup)
+  - [`licenseResponseCallback`](#licenseresponsecallback)
+  - [`drmSystems`](#drmsystems)
+  - [`drmSystems[KEY-SYSTEM].generateRequest](#drmsystemskey-systemgeneraterequest)
+  - [`drmSystemOptions`](#drmsystemoptions)
+  - [`requestMediaKeySystemAccessFunc`](#requestmediakeysystemaccessfunc)
   - [`cmcd`](#cmcd)
 - [Video Binding/Unbinding API](#video-bindingunbinding-api)
   - [`hls.attachMedia(videoElement)`](#hlsattachmediavideoelement)
@@ -118,7 +123,7 @@
   - [`hls.maxHdcpLevel`](#hlsmaxhdcplevel)
   - [`hls.capLevelToPlayerSize`](#hlscapleveltoplayersize)
   - [`hls.bandwidthEstimate`](#hlsbandwidthestimate)
-  - [`hls.removeLevel(levelIndex, urlId)`](#hlsremoveLevel)
+  - [`hls.removeLevel(levelIndex, urlId)`](#hlsremovelevellevelindex-urlid)
 - [Version Control](#version-control)
   - [`Hls.version`](#hlsversion)
 - [Network Loading Control API](#network-loading-control-api)
@@ -144,6 +149,7 @@
   - [Network Errors](#network-errors)
   - [Media Errors](#media-errors)
   - [Mux Errors](#mux-errors)
+  - [EME Key System Errors](#eme-key-system-errors)
   - [Other Errors](#other-errors)
 - [Objects](#objects)
   - [Level](#level)
@@ -633,7 +639,7 @@ Override current Media Source duration to `Infinity` for a live broadcast.
 Useful, if you are building a player which relies on native UI capabilities in modern browsers.
 If you want to have a native Live UI in environments like iOS Safari, Safari, Android Google Chrome, etc. set this value to `true`.
 
-### `liveBackBufferLength`
+### `liveBackBufferLength` (deprecated)
 
 `liveBackBufferLength` has been deprecated. Use `backBufferLength` instead.
 

docs/API.md

@@ -1,3 +1,14 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+**Table of Contents**
+
+- [Design principle](#design-principle)
+- [Code structure](#code-structure)
+- [Error detection and Handling](#error-detection-and-handling)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
 ## Design principle
 
 design idea is pretty simple :