Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move @internal markers to individual members #592

Merged
merged 4 commits into from
Mar 28, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,3 +33,6 @@ jobs:

- name: Test published files
run: npm run test-published-files

- name: Test declarations
run: npm run test-declarations
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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 ..",
Expand Down
4 changes: 2 additions & 2 deletions src/Algorithm.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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) {
Expand Down
8 changes: 5 additions & 3 deletions src/Biblio.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,6 @@ class EnvRec {
}
}

/*@internal*/
export default class Biblio {
private _byId: { [id: string]: BiblioEntry };
private _location: string;
Expand Down Expand Up @@ -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]!;
Expand All @@ -209,6 +209,7 @@ export default class Biblio {
}
}

/** @internal*/
createNamespace(ns: string, parent: string) {
const existingNs = this._nsToEnvRec[ns];
if (existingNs) {
Expand Down Expand Up @@ -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');
Expand Down Expand Up @@ -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 {
Expand Down
10 changes: 2 additions & 8 deletions src/Builder.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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[] = [];
}
41 changes: 19 additions & 22 deletions src/Clause.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -250,7 +247,7 @@ export default class Clause extends Builder {
}
}

buildNotes() {
/** @internal */ buildNotes() {
if (this.notes.length === 1) {
this.notes[0].build();
} else {
Expand All @@ -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 {
Expand Down
1 change: 0 additions & 1 deletion src/Dfn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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')) {
Expand Down
3 changes: 1 addition & 2 deletions src/Eqn.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
}

Expand Down
9 changes: 4 additions & 5 deletions src/Example.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
3 changes: 1 addition & 2 deletions src/Grammar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down Expand Up @@ -96,5 +95,5 @@ export default class Grammar extends Builder {
});
}

static elements = ['EMU-GRAMMAR'];
static readonly elements = ['EMU-GRAMMAR'] as const;
}
3 changes: 1 addition & 2 deletions src/GrammarAnnotation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
8 changes: 3 additions & 5 deletions src/Import.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -77,7 +76,6 @@ export default class Import extends Builder {
}
}

/*@internal*/
export interface EmuImportElement extends HTMLElement {
href: string;
dom?: JSDOM;
Expand Down
1 change: 0 additions & 1 deletion src/Menu.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
Expand Down
11 changes: 5 additions & 6 deletions src/NonTerminal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
9 changes: 4 additions & 5 deletions src/Note.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
7 changes: 3 additions & 4 deletions src/ProdRef.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
27 changes: 13 additions & 14 deletions src/Production.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -147,5 +146,5 @@ export default class Production extends Builder {
}
}

static elements = ['EMU-PRODUCTION'];
static readonly elements = ['EMU-PRODUCTION'] as const;
}
7 changes: 3 additions & 4 deletions src/RHS.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
Loading
Loading