Skip to content

Commit f782180

Browse files
jkowalleckjkowalleck
authored
docs: Improve docs (#450)
* TypeDoc render internals * make names of internals unique, for better readability of docs Signed-off-by: Jan Kowalleck <[email protected]>
1 parent e5028d7 commit f782180

File tree

6 files changed

+56
-39
lines changed

6 files changed

+56
-39
lines changed

‎package-lock.json‎

Lines changed: 17 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@
5959
"npm-run-all": "^4.1.5",
6060
"ts-loader": "9.4.2",
6161
"typedoc": "^0.23.24",
62+
"typedoc-plugin-missing-exports": "^1.0.0",
6263
"typescript": "4.9.4",
6364
"webpack": "5.75.0",
6465
"webpack-cli": "5.0.1",

‎src/_helpers/sortable.ts‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,9 @@ export interface Comparable<TOther> {
3535

3636
const compareObjectsSymbol = Symbol('internal compare function')
3737

38-
abstract class SortableSet<TItem> extends Set<TItem> implements Sortable<TItem>, Comparable<Sortable<TItem>> {
38+
export type SortableIterable<TItem> = Iterable<TItem> & Sortable<TItem>
39+
40+
abstract class SortableSet<TItem> extends Set<TItem> implements SortableIterable<TItem>, Comparable<Sortable<TItem>> {
3941
/**
4042
* Comparator function to apply to two items.
4143
*/

‎src/serialize/json/normalize.ts‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
1818
*/
1919

2020
import { isNotUndefined } from '../../_helpers/notUndefined'
21-
import type { Sortable } from '../../_helpers/sortable'
21+
import type { SortableIterable } from '../../_helpers/sortable'
2222
import type { Stringable } from '../../_helpers/stringable'
2323
import { treeIteratorSymbol } from '../../_helpers/tree'
2424
import * as Models from '../../models'
@@ -98,9 +98,7 @@ const schemaUrl: ReadonlyMap<SpecVersion, string> = new Map([
9898
[SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom-1.4.schema.json']
9999
])
100100

101-
type SortableIterable<T> = Iterable<T> & Sortable<T>
102-
103-
interface Normalizer<TModel, TNormalized> {
101+
interface JsonNormalizer<TModel, TNormalized> {
104102
normalize: (data: TModel, options: NormalizerOptions) => TNormalized | undefined
105103

106104
/** @since 1.5.1 */
@@ -109,10 +107,10 @@ interface Normalizer<TModel, TNormalized> {
109107
normalizeRepository?: ['normalizeIterable']
110108
}
111109

112-
abstract class Base<TModel, TNormalized=object> implements Normalizer<TModel, TNormalized> {
110+
abstract class BaseJsonNormalizer<TModel, TNormalized=object> implements JsonNormalizer<TModel, TNormalized> {
113111
protected readonly _factory: Factory
114112

115-
constructor (factory: Base<TModel, TNormalized>['factory']) {
113+
constructor (factory: Factory) {
116114
this._factory = factory
117115
}
118116

@@ -127,7 +125,7 @@ abstract class Base<TModel, TNormalized=object> implements Normalizer<TModel, TN
127125
* since empty strings need to be treated as undefined/null
128126
*/
129127

130-
export class BomNormalizer extends Base<Models.Bom> {
128+
export class BomNormalizer extends BaseJsonNormalizer<Models.Bom> {
131129
normalize (data: Models.Bom, options: NormalizerOptions): Normalized.Bom {
132130
return {
133131
$schema: schemaUrl.get(this._factory.spec.version),
@@ -147,7 +145,7 @@ export class BomNormalizer extends Base<Models.Bom> {
147145
}
148146
}
149147

150-
export class MetadataNormalizer extends Base<Models.Metadata> {
148+
export class MetadataNormalizer extends BaseJsonNormalizer<Models.Metadata> {
151149
normalize (data: Models.Metadata, options: NormalizerOptions): Normalized.Metadata {
152150
const orgEntityNormalizer = this._factory.makeForOrganizationalEntity()
153151
return {
@@ -171,7 +169,7 @@ export class MetadataNormalizer extends Base<Models.Metadata> {
171169
}
172170
}
173171

174-
export class ToolNormalizer extends Base<Models.Tool> {
172+
export class ToolNormalizer extends BaseJsonNormalizer<Models.Tool> {
175173
normalize (data: Models.Tool, options: NormalizerOptions): Normalized.Tool {
176174
return {
177175
vendor: data.vendor || undefined,
@@ -199,7 +197,7 @@ export class ToolNormalizer extends Base<Models.Tool> {
199197
normalizeRepository = this.normalizeIterable
200198
}
201199

202-
export class HashNormalizer extends Base<Models.Hash> {
200+
export class HashNormalizer extends BaseJsonNormalizer<Models.Hash> {
203201
normalize ([algorithm, content]: Models.Hash, options: NormalizerOptions): Normalized.Hash | undefined {
204202
const spec = this._factory.spec
205203
return spec.supportsHashAlgorithm(algorithm) && spec.supportsHashValue(content)
@@ -225,7 +223,7 @@ export class HashNormalizer extends Base<Models.Hash> {
225223
normalizeRepository = this.normalizeIterable
226224
}
227225

228-
export class OrganizationalContactNormalizer extends Base<Models.OrganizationalContact> {
226+
export class OrganizationalContactNormalizer extends BaseJsonNormalizer<Models.OrganizationalContact> {
229227
normalize (data: Models.OrganizationalContact, options: NormalizerOptions): Normalized.OrganizationalContact {
230228
return {
231229
name: data.name || undefined,
@@ -249,7 +247,7 @@ export class OrganizationalContactNormalizer extends Base<Models.OrganizationalC
249247
normalizeRepository = this.normalizeIterable
250248
}
251249

252-
export class OrganizationalEntityNormalizer extends Base<Models.OrganizationalEntity> {
250+
export class OrganizationalEntityNormalizer extends BaseJsonNormalizer<Models.OrganizationalEntity> {
253251
normalize (data: Models.OrganizationalEntity, options: NormalizerOptions): Normalized.OrganizationalEntity {
254252
const urls = normalizeStringableIter(data.url, options)
255253
.filter(JsonSchema.isIriReference)
@@ -265,7 +263,7 @@ export class OrganizationalEntityNormalizer extends Base<Models.OrganizationalEn
265263
}
266264
}
267265

268-
export class ComponentNormalizer extends Base<Models.Component> {
266+
export class ComponentNormalizer extends BaseJsonNormalizer<Models.Component> {
269267
normalize (data: Models.Component, options: NormalizerOptions): Normalized.Component | undefined {
270268
const spec = this._factory.spec
271269
const version: string = data.version ?? ''
@@ -325,7 +323,7 @@ export class ComponentNormalizer extends Base<Models.Component> {
325323
normalizeRepository = this.normalizeIterable
326324
}
327325

328-
export class LicenseNormalizer extends Base<Models.License> {
326+
export class LicenseNormalizer extends BaseJsonNormalizer<Models.License> {
329327
normalize (data: Models.License, options: NormalizerOptions): Normalized.License {
330328
switch (true) {
331329
case data instanceof Models.NamedLicense:
@@ -383,7 +381,7 @@ export class LicenseNormalizer extends Base<Models.License> {
383381
normalizeRepository = this.normalizeIterable
384382
}
385383

386-
export class SWIDNormalizer extends Base<Models.SWID> {
384+
export class SWIDNormalizer extends BaseJsonNormalizer<Models.SWID> {
387385
normalize (data: Models.SWID, options: NormalizerOptions): Normalized.SWID {
388386
const url = data.url?.toString()
389387
return {
@@ -402,7 +400,7 @@ export class SWIDNormalizer extends Base<Models.SWID> {
402400
}
403401
}
404402

405-
export class ExternalReferenceNormalizer extends Base<Models.ExternalReference> {
403+
export class ExternalReferenceNormalizer extends BaseJsonNormalizer<Models.ExternalReference> {
406404
normalize (data: Models.ExternalReference, options: NormalizerOptions): Normalized.ExternalReference | undefined {
407405
return this._factory.spec.supportsExternalReferenceType(data.type)
408406
? {
@@ -428,7 +426,7 @@ export class ExternalReferenceNormalizer extends Base<Models.ExternalReference>
428426
normalizeRepository = this.normalizeIterable
429427
}
430428

431-
export class AttachmentNormalizer extends Base<Models.Attachment> {
429+
export class AttachmentNormalizer extends BaseJsonNormalizer<Models.Attachment> {
432430
normalize (data: Models.Attachment, options: NormalizerOptions): Normalized.Attachment {
433431
return {
434432
content: data.content,
@@ -438,7 +436,7 @@ export class AttachmentNormalizer extends Base<Models.Attachment> {
438436
}
439437
}
440438

441-
export class PropertyNormalizer extends Base<Models.Property> {
439+
export class PropertyNormalizer extends BaseJsonNormalizer<Models.Property> {
442440
normalize (data: Models.Property, options: NormalizerOptions): Normalized.Property {
443441
return {
444442
name: data.name,
@@ -459,7 +457,7 @@ export class PropertyNormalizer extends Base<Models.Property> {
459457
normalizeRepository = this.normalizeIterable
460458
}
461459

462-
export class DependencyGraphNormalizer extends Base<Models.Bom> {
460+
export class DependencyGraphNormalizer extends BaseJsonNormalizer<Models.Bom> {
463461
normalize (data: Models.Bom, options: NormalizerOptions): Normalized.Dependency[] | undefined {
464462
const allRefs = new Map<Models.BomRef, Models.BomRefRepository>()
465463
if (data.metadata.component !== undefined) {

‎src/serialize/xml/normalize.ts‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Copyright (c) OWASP Foundation. All Rights Reserved.
1818
*/
1919

2020
import { isNotUndefined } from '../../_helpers/notUndefined'
21-
import type { Sortable } from '../../_helpers/sortable'
21+
import type { SortableIterable } from '../../_helpers/sortable'
2222
import type { Stringable } from '../../_helpers/stringable'
2323
import { treeIteratorSymbol } from '../../_helpers/tree'
2424
import * as Models from '../../models'
@@ -98,9 +98,7 @@ const xmlNamespace: ReadonlyMap<SpecVersion, string> = new Map([
9898
[SpecVersion.v1dot4, 'http://cyclonedx.org/schema/bom/1.4']
9999
])
100100

101-
type SortableIterable<T> = Iterable<T> & Sortable<T>
102-
103-
interface Normalizer<TModel, TNormalized> {
101+
interface XmlNormalizer<TModel, TNormalized> {
104102
normalize: (data: TModel, options: NormalizerOptions, elementName?: string) => TNormalized | undefined
105103

106104
/** @since 1.5.1 */
@@ -109,10 +107,10 @@ interface Normalizer<TModel, TNormalized> {
109107
normalizeRepository?: ['normalizeIterable']
110108
}
111109

112-
abstract class Base<TModel, TNormalized=SimpleXml.Element> implements Normalizer<TModel, TNormalized> {
110+
abstract class BaseXmlNormalizer<TModel, TNormalized=SimpleXml.Element> implements XmlNormalizer<TModel, TNormalized> {
113111
protected readonly _factory: Factory
114112

115-
constructor (factory: Base<TModel, TNormalized>['factory']) {
113+
constructor (factory: Factory) {
116114
this._factory = factory
117115
}
118116

@@ -130,7 +128,7 @@ abstract class Base<TModel, TNormalized=SimpleXml.Element> implements Normalizer
130128
* since empty strings need to be treated as undefined/null
131129
*/
132130

133-
export class BomNormalizer extends Base<Models.Bom> {
131+
export class BomNormalizer extends BaseXmlNormalizer<Models.Bom> {
134132
normalize (data: Models.Bom, options: NormalizerOptions): SimpleXml.Element {
135133
const components: SimpleXml.Element = {
136134
// spec < 1.4 always requires a 'components' element
@@ -162,7 +160,7 @@ export class BomNormalizer extends Base<Models.Bom> {
162160
}
163161
}
164162

165-
export class MetadataNormalizer extends Base<Models.Metadata> {
163+
export class MetadataNormalizer extends BaseXmlNormalizer<Models.Metadata> {
166164
normalize (data: Models.Metadata, options: NormalizerOptions, elementName: string): SimpleXml.Element {
167165
const orgEntityNormalizer = this._factory.makeForOrganizationalEntity()
168166
const timestamp: SimpleXml.Element | undefined = data.timestamp === undefined
@@ -208,7 +206,7 @@ export class MetadataNormalizer extends Base<Models.Metadata> {
208206
}
209207
}
210208

211-
export class ToolNormalizer extends Base<Models.Tool> {
209+
export class ToolNormalizer extends BaseXmlNormalizer<Models.Tool> {
212210
normalize (data: Models.Tool, options: NormalizerOptions, elementName: string): SimpleXml.Element {
213211
const hashes: SimpleXml.Element | undefined = data.hashes.size > 0
214212
? {
@@ -252,7 +250,7 @@ export class ToolNormalizer extends Base<Models.Tool> {
252250
normalizeRepository = this.normalizeIterable
253251
}
254252

255-
export class HashNormalizer extends Base<Models.Hash> {
253+
export class HashNormalizer extends BaseXmlNormalizer<Models.Hash> {
256254
normalize ([algorithm, content]: Models.Hash, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
257255
const spec = this._factory.spec
258256
return spec.supportsHashAlgorithm(algorithm) && spec.supportsHashValue(content)
@@ -280,7 +278,7 @@ export class HashNormalizer extends Base<Models.Hash> {
280278
normalizeRepository = this.normalizeIterable
281279
}
282280

283-
export class OrganizationalContactNormalizer extends Base<Models.OrganizationalContact> {
281+
export class OrganizationalContactNormalizer extends BaseXmlNormalizer<Models.OrganizationalContact> {
284282
normalize (data: Models.OrganizationalContact, options: NormalizerOptions, elementName: string): SimpleXml.Element {
285283
return {
286284
type: 'element',
@@ -306,7 +304,7 @@ export class OrganizationalContactNormalizer extends Base<Models.OrganizationalC
306304
normalizeRepository = this.normalizeIterable
307305
}
308306

309-
export class OrganizationalEntityNormalizer extends Base<Models.OrganizationalEntity> {
307+
export class OrganizationalEntityNormalizer extends BaseXmlNormalizer<Models.OrganizationalEntity> {
310308
normalize (data: Models.OrganizationalEntity, options: NormalizerOptions, elementName: string): SimpleXml.Element {
311309
return {
312310
type: 'element',
@@ -321,7 +319,7 @@ export class OrganizationalEntityNormalizer extends Base<Models.OrganizationalEn
321319
}
322320
}
323321

324-
export class ComponentNormalizer extends Base<Models.Component> {
322+
export class ComponentNormalizer extends BaseXmlNormalizer<Models.Component> {
325323
normalize (data: Models.Component, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
326324
const spec = this._factory.spec
327325
if (!spec.supportsComponentType(data.type)) {
@@ -421,7 +419,7 @@ export class ComponentNormalizer extends Base<Models.Component> {
421419
normalizeRepository = this.normalizeIterable
422420
}
423421

424-
export class LicenseNormalizer extends Base<Models.License> {
422+
export class LicenseNormalizer extends BaseXmlNormalizer<Models.License> {
425423
normalize (data: Models.License, options: NormalizerOptions): SimpleXml.Element {
426424
switch (true) {
427425
case data instanceof Models.NamedLicense:
@@ -487,7 +485,7 @@ export class LicenseNormalizer extends Base<Models.License> {
487485
normalizeRepository = this.normalizeIterable
488486
}
489487

490-
export class SWIDNormalizer extends Base<Models.SWID> {
488+
export class SWIDNormalizer extends BaseXmlNormalizer<Models.SWID> {
491489
normalize (data: Models.SWID, options: NormalizerOptions, elementName: string): SimpleXml.Element {
492490
const url = data.url?.toString()
493491
return {
@@ -514,7 +512,7 @@ export class SWIDNormalizer extends Base<Models.SWID> {
514512
}
515513
}
516514

517-
export class ExternalReferenceNormalizer extends Base<Models.ExternalReference> {
515+
export class ExternalReferenceNormalizer extends BaseXmlNormalizer<Models.ExternalReference> {
518516
normalize (data: Models.ExternalReference, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
519517
const url = data.url.toString()
520518
return this._factory.spec.supportsExternalReferenceType(data.type) &&
@@ -548,7 +546,7 @@ export class ExternalReferenceNormalizer extends Base<Models.ExternalReference>
548546
normalizeRepository = this.normalizeIterable
549547
}
550548

551-
export class AttachmentNormalizer extends Base<Models.Attachment> {
549+
export class AttachmentNormalizer extends BaseXmlNormalizer<Models.Attachment> {
552550
normalize (data: Models.Attachment, options: NormalizerOptions, elementName: string): SimpleXml.Element {
553551
return {
554552
type: 'element',
@@ -562,7 +560,7 @@ export class AttachmentNormalizer extends Base<Models.Attachment> {
562560
}
563561
}
564562

565-
export class PropertyNormalizer extends Base<Models.Property> {
563+
export class PropertyNormalizer extends BaseXmlNormalizer<Models.Property> {
566564
normalize (data: Models.Property, options: NormalizerOptions, elementName: string): SimpleXml.Element {
567565
return {
568566
type: 'element',
@@ -587,7 +585,7 @@ export class PropertyNormalizer extends Base<Models.Property> {
587585
normalizeRepository = this.normalizeIterable
588586
}
589587

590-
export class DependencyGraphNormalizer extends Base<Models.Bom> {
588+
export class DependencyGraphNormalizer extends BaseXmlNormalizer<Models.Bom> {
591589
normalize (data: Models.Bom, options: NormalizerOptions, elementName: string): SimpleXml.Element | undefined {
592590
const allRefs = new Map<Models.BomRef, Models.BomRefRepository>()
593591
if (data.metadata.component !== undefined) {

‎typedoc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"hideGenerator": true,
77
"readme": "none",
88
"name": "CycloneDX JavaScript Library",
9+
"excludeExternals": true,
910
"externalSymbolLinkMappings": {
1011
"packageurl-js": {
1112
"PackageURL": "https://github.com/package-url/packageurl-js#usage-examples"

0 commit comments

Comments
 (0)