Move @internal markers to individual members (#592)

.github/workflows/check.yml

@@ -33,3 +33,6 @@ jobs:
 
       - name: Test published files
         run: npm run test-published-files
+
+      - name: Test declarations
+        run: npm run test-declarations

package.json

@@ -5,13 +5,14 @@
 	"main": "lib/ecmarkup.js",
 	"typings": "lib/ecmarkup.d.ts",
 	"scripts": {
-		"build": "tsc -sourceMap",
+		"build": "tsc -sourceMap -declarationMap",
 		"build-release": "tsc",
 		"build-spec": "mkdir -p docs && node bin/ecmarkup.js spec/index.html docs/index.html --assets-dir=docs",
 		"prepack": "safe-publish-latest && npm run build-release",
 		"format-spec": "node bin/emu-format.js --write spec/index.html",
 		"test": "mocha",
 		"test-baselines": "mocha test/baselines.js",
+		"test-declarations": "tsc -p tsconfig.test.json",
 		"update-baselines": "npm --update-baselines run test-baselines",
 		"pretest-published-files": "rm -rf \"ecmarkup-$npm_package_version.tgz\" package",
 		"test-published-files": "npm pack && tar zxvf \"ecmarkup-$npm_package_version.tgz\" && cp -r test package/test && cd package && npm test && cd ..",

src/Algorithm.ts

@@ -28,7 +28,6 @@ export type AlgorithmElementWithTree = HTMLElement & {
   originalHtml: string;
 };
 
-/*@internal*/
 export default class Algorithm extends Builder {
   static async enter(context: Context) {
     context.inAlg = true;
@@ -216,7 +215,8 @@ export default class Algorithm extends Builder {
   static exit(context: Context) {
     context.inAlg = false;
   }
-  static elements = ['EMU-ALG'];
+
+  static readonly elements = ['EMU-ALG'] as const;
 }
 
 function getStepNumbers(item: Element) {

src/Biblio.ts

@@ -65,7 +65,6 @@ class EnvRec {
   }
 }
 
-/*@internal*/
 export default class Biblio {
   private _byId: { [id: string]: BiblioEntry };
   private _location: string;
@@ -185,6 +184,7 @@ export default class Biblio {
     return undefined;
   }
 
+  /** @internal*/
   add(entry: PartialBiblioEntry & { location?: string }, ns?: string | null) {
     ns = ns || this._location;
     const env = this._nsToEnvRec[ns]!;
@@ -209,6 +209,7 @@ export default class Biblio {
     }
   }
 
+  /** @internal*/
   createNamespace(ns: string, parent: string) {
     const existingNs = this._nsToEnvRec[ns];
     if (existingNs) {
@@ -252,6 +253,7 @@ export default class Biblio {
     return root;
   }
 
+  /** @internal*/
   addExternalBiblio(biblio: ExportedBiblio) {
     for (const item of biblio.entries) {
       this.add({ location: biblio.location, ...item }, 'external');
@@ -342,13 +344,13 @@ export interface AlgorithmBiblioEntry extends BiblioEntryBase {
   signature: null | Signature;
   effects: string[];
   skipGlobalChecks?: boolean;
-  /*@internal*/ _node?: Element;
+  /** @internal*/ _node?: Element;
 }
 
 export interface ProductionBiblioEntry extends BiblioEntryBase {
   type: 'production';
   name: string;
-  /*@internal*/ _instance?: Production;
+  /** @internal*/ _instance?: Production;
 }
 
 export interface ClauseBiblioEntry extends BiblioEntryBase {

src/Builder.ts

@@ -2,14 +2,8 @@ import type Spec from './Spec';
 import type { Context } from './Context';
 
 // We use this instead of `typeof Builder` because using the class as the type also requires derived constructors to be subtypes of the base constructor, which is irritating.
-/*@internal*/
-export interface BuilderInterface {
-  elements: string[];
-  enter(context: Context): void;
-  exit(context: Context): void;
-}
+export type BuilderInterface = Omit<typeof Builder, never>;
 
-/*@internal*/
 export default class Builder {
   public spec: Spec;
   public node: HTMLElement;
@@ -40,5 +34,5 @@ export default class Builder {
   }
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   static exit(context: Context): void {}
-  static elements: string[] = [];
+  static readonly elements: readonly string[] = [];
 }

src/Clause.ts

@@ -38,26 +38,23 @@ export function extractStructuredHeader(header: Element): Element | null {
   return dl;
 }
 
-/*@internal*/
 export default class Clause extends Builder {
-  id: string;
-  namespace: string;
-  parentClause: Clause;
-  header: Element | null;
-  // @ts-ignore skipping the strictPropertyInitialization check
-  title: string | null;
-  // @ts-ignore skipping the strictPropertyInitialization check
-  titleHTML: string;
-  subclauses: Clause[];
-  number: string;
-  aoid: string | null;
-  type: string | null;
-  notes: Note[];
-  editorNotes: Note[];
-  examples: Example[];
-  readonly effects: string[]; // this is held by identity and mutated by Spec.ts
-  signature: Signature | null;
-  skipGlobalChecks: boolean;
+  /** @internal */ id: string;
+  /** @internal */ namespace: string;
+  /** @internal */ parentClause: Clause;
+  /** @internal */ header: Element | null;
+  /** @internal */ title!: string | null;
+  /** @internal */ titleHTML!: string;
+  /** @internal */ subclauses: Clause[];
+  /** @internal */ number: string;
+  /** @internal */ aoid: string | null;
+  /** @internal */ type: string | null;
+  /** @internal */ notes: Note[];
+  /** @internal */ editorNotes: Note[];
+  /** @internal */ examples: Example[];
+  /** @internal */ readonly effects: string[]; // this is held by identity and mutated by Spec.ts
+  /** @internal */ signature: Signature | null;
+  /** @internal */ skipGlobalChecks: boolean;
 
   constructor(spec: Spec, node: HTMLElement, parent: Clause, number: string) {
     super(spec, node);
@@ -131,7 +128,7 @@ export default class Clause extends Builder {
     }
   }
 
-  buildStructuredHeader(header: Element, headerSurrogate: Element = header) {
+  /** @internal */ buildStructuredHeader(header: Element, headerSurrogate: Element = header) {
     const dl = extractStructuredHeader(headerSurrogate);
     if (dl === null) {
       return;
@@ -250,7 +247,7 @@ export default class Clause extends Builder {
     }
   }
 
-  buildNotes() {
+  /** @internal */ buildNotes() {
     if (this.notes.length === 1) {
       this.notes[0].build();
     } else {
@@ -263,7 +260,7 @@ export default class Clause extends Builder {
     this.editorNotes.forEach(note => note.build());
   }
 
-  buildExamples() {
+  /** @internal */ buildExamples() {
     if (this.examples.length === 1) {
       this.examples[0].build();
     } else {

src/Dfn.ts

@@ -4,7 +4,6 @@ import type { Context } from './Context';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class Dfn extends Builder {
   static async enter({ spec, node, clauseStack }: Context) {
     if (!node.hasAttribute('tabindex')) {

src/Eqn.ts

@@ -4,10 +4,9 @@ import Builder from './Builder';
 import * as emd from 'ecmarkdown';
 import * as utils from './utils';
 
-/*@internal*/
 export default class Eqn extends Builder {
   // @ts-ignore
-  constructor() {
+  private constructor() {
     throw new Error('not actually constructible');
   }
 

src/Example.ts

@@ -4,12 +4,11 @@ import type { Context } from './Context';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class Example extends Builder {
-  clause: Clause;
-  caption: string | null;
-  id: string | undefined;
-  static elements = ['EMU-EXAMPLE'];
+  /** @internal */ clause: Clause;
+  /** @internal */ caption: string | null;
+  /** @internal */ id: string | undefined;
+  static readonly elements = ['EMU-EXAMPLE'] as const;
 
   constructor(spec: Spec, node: HTMLElement, clause: Clause) {
     super(spec, node);

src/Grammar.ts

@@ -13,7 +13,6 @@ export type AugmentedGrammarEle = HTMLElement & {
   grammarSource: SourceFile;
 };
 
-/*@internal*/
 export default class Grammar extends Builder {
   static async enter({ spec, node, clauseStack }: Context) {
     if ('grammarkdownOut' in node) {
@@ -96,5 +95,5 @@ export default class Grammar extends Builder {
     });
   }
 
-  static elements = ['EMU-GRAMMAR'];
+  static readonly elements = ['EMU-GRAMMAR'] as const;
 }

src/GrammarAnnotation.ts

@@ -3,9 +3,8 @@ import type Production from './Production';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class GrammarAnnotation extends Builder {
-  production: Production;
+  /** @internal */ production: Production;
 
   constructor(spec: Spec, prod: Production, node: HTMLElement) {
     super(spec, node);

src/Import.ts

@@ -5,11 +5,10 @@ import * as utils from './utils';
 import * as path from 'path';
 import type { JSDOM } from 'jsdom';
 
-/*@internal*/
 export default class Import extends Builder {
-  public importLocation: string;
-  public relativeRoot: string;
-  public source: string;
+  /** @internal */ public importLocation: string;
+  /** @internal */ public relativeRoot: string;
+  /** @internal */ public source: string;
 
   constructor(
     spec: Spec,
@@ -77,7 +76,6 @@ export default class Import extends Builder {
   }
 }
 
-/*@internal*/
 export interface EmuImportElement extends HTMLElement {
   href: string;
   dom?: JSDOM;

src/Menu.ts

@@ -3,7 +3,6 @@ import type Spec from './Spec';
 
 import Toc from './Toc';
 
-/*@internal*/
 export default function makeMenu(spec: Spec) {
   const pinContainer = spec.doc.createElement('div');
   pinContainer.setAttribute('id', 'menu-pins');

src/NonTerminal.ts

@@ -4,14 +4,13 @@ import type { BiblioEntry } from './Biblio';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class NonTerminal extends Builder {
-  params: string | null;
-  optional: boolean;
-  namespace: string;
-  entry?: BiblioEntry;
+  /** @internal */ params: string | null;
+  /** @internal */ optional: boolean;
+  /** @internal */ namespace: string;
+  /** @internal */ entry?: BiblioEntry;
 
-  static elements = ['EMU-NT'];
+  static readonly elements = ['EMU-NT'] as const;
 
   constructor(spec: Spec, node: HTMLElement, namespace: string) {
     super(spec, node);

src/Note.ts

@@ -4,12 +4,11 @@ import type { Context } from './Context';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class Note extends Builder {
-  clause: Clause;
-  id?: string;
-  type: string; // normal, editor
-  static elements = ['EMU-NOTE'];
+  /** @internal */ clause: Clause;
+  /** @internal */ id?: string;
+  /** @internal */ type: string; // normal, editor
+  static readonly elements = ['EMU-NOTE'] as const;
 
   constructor(spec: Spec, node: HTMLElement, clause: Clause) {
     super(spec, node);

src/ProdRef.ts

@@ -4,12 +4,11 @@ import type Spec from './Spec';
 import Builder from './Builder';
 import { shouldInline } from './utils';
 
-/*@internal*/
 export default class ProdRef extends Builder {
-  public namespace: string;
-  public name: string;
+  /** @internal */ public namespace: string;
+  /** @internal */ public name: string;
 
-  static elements = ['EMU-PRODREF'];
+  static readonly elements = ['EMU-PRODREF'] as const;
 
   constructor(spec: Spec, node: HTMLElement, namespace: string) {
     super(spec, node);

src/Production.ts

@@ -8,20 +8,19 @@ import Terminal from './Terminal';
 import Builder from './Builder';
 import * as utils from './utils';
 
-/*@internal*/
 export default class Production extends Builder {
-  static byName = {};
-
-  type: string | null;
-  name: string;
-  params: string | null;
-  optional: boolean;
-  oneOf: boolean;
-  rhses: RHS[];
-  rhsesById: { [id: string]: RHS };
-  namespace: string;
-  primary: boolean;
-  id: string | undefined;
+  /** @internal */ static byName = {};
+
+  /** @internal */ type: string | null;
+  /** @internal */ name: string;
+  /** @internal */ params: string | null;
+  /** @internal */ optional: boolean;
+  /** @internal */ oneOf: boolean;
+  /** @internal */ rhses: RHS[];
+  /** @internal */ rhsesById: { [id: string]: RHS };
+  /** @internal */ namespace: string;
+  /** @internal */ primary: boolean;
+  /** @internal */ id: string | undefined;
 
   constructor(spec: Spec, node: HTMLElement, namespace: string) {
     super(spec, node);
@@ -147,5 +146,5 @@ export default class Production extends Builder {
     }
   }
 
-  static elements = ['EMU-PRODUCTION'];
+  static readonly elements = ['EMU-PRODUCTION'] as const;
 }

src/RHS.ts

@@ -3,11 +3,10 @@ import type Production from './Production';
 
 import Builder from './Builder';
 
-/*@internal*/
 export default class RHS extends Builder {
-  production: Production;
-  constraints: string | null;
-  alternativeId: string | null;
+  /** @internal */ production: Production;
+  /** @internal */ constraints: string | null;
+  /** @internal */ alternativeId: string | null;
 
   constructor(spec: Spec, prod: Production, node: HTMLElement) {
     super(spec, node);