Declaring Internal Use Items

[ycw]

cross track: three-types/three-ts-types#172

Option 1 most accurate typing (three-ts-types goals)

threejs api docs as SSOT, make sure all (three.js) public APIs are documented, then (three-ts-type) its safe to include declarations for all undocumented items, and tags them @internal

tracks:

• Docs: Some APIs are Undocumented mrdoob/three.js#23509
• Docs: Missing API Docs for Type Assertion .is* ?? mrdoob/three.js#23527
• Docs: Remove Dot Prefix from Property Items  mrdoob/three.js#23529
• Docs: Group Property Items mrdoob/three.js#23532
• Docs: Some Override Items are Undocumented mrdoob/three.js#23536
• Docs: use <p> for supporting paragraphs mrdoob/three.js#23522

snapshots:

• three.d.ts (playground) (build)

Option 2 just enough for the norm (will break the goals)

updates:

• three-ts-type had updated its goal
  Add policy for undocumented public items three-types/three-ts-types#172 (comment)

Option 3 most accurate intention (future)

Ask (three.js) to adopt private class field (caniuse), then (three-ts-types) in no doubt, excludes declarations for them. If (three.js) finally delivers a "std" lib, then the "core" items exposed for "std" used only should be included and tagged @internal (three-ts-types).

tracks:

• Material: use class properties mrdoob/three.js#24237
• Decide whether class fields can be used in core mrdoob/three.js#25105

Option 4 most misleading typing (current)

(three-ts-types) includes declarations for undocumented APIs w/o @internal or @remarks undocumented, imagine that:

// three-ts-types has declaration for Audio `.loop`, so one might attempt to:
audio.loop = true  
// Bugged silently, the actual source doesn't loop. After diving into the docs, 
// we realized that .loop is undocumented, and .setLoop() should be used instead.

related:

• GLTFLoader: Expose GLTFParser. mrdoob/three.js#24764 (comment)