Generated documentation for ExternalRef shows superclass of itself

[goneall]

ExternalRef should not have any superclass, bit it shows itself as a superclass in the generated documentation.

I'm not sure if this is an issue with the model, SpecParser of MkDocs in the spec - so I thought I would post this here to start.

See https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/ExternalRef/

[bact]

In the Metadata section of the model Markdown file, it looks fine (SubclassOf: none):

spdx-3-model/model/Core/Classes/ExternalRef.md

Lines 14 to 18 in 01ca260

	## Metadata
	- name: ExternalRef
	- SubclassOf: none
	- Instantiability: Concrete

[bact]

We may need to target this as 3.0.2 ?
(Or even 3.0.1 ? - since this is not a change to the model itself, but the rendering/generation of the model documentation?)

[bact]

Search ("SubclassOf: none"), found same issue with these classes:

• https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/Element/
• https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/ExternalIdentifier/
• https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/ExternalMap/
• https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/ExternalRef/
• https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/PositiveIntegerRange/

[bact]

This probably more of a layout/formatting/choice of word issue.

There are also other classes that have the same issue, like:
https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/IntegrityMethod/

https://spdx.github.io/spdx-spec/v3.0.1/model/Core/Classes/Hash/

Probably have to have some indication that, the class at the top is not the superclass but "this class".

[bact]

Relevant code block in spec-parser:

## Superclasses

{% set full_inheritance_stack = [fqname] + inheritance_stack %}
{% for super in full_inheritance_stack | reverse %}
{{ ' ' * ((loop.index-1) * 6) }}
  {% if loop.last %}
{{type_link(super)}}
  {% else %}
{{type_link(super)}}<br />
  {% endif %}
{% endfor %}

https://github.com/spdx/spec-parser/blob/3d1d92eb1ccd95f65d3cc54a7d6837b32cf6aeab/spec_parser/templates/mkdocs/class.md.j2#L13-L23

[zvr]

Right -- it's the chain of classes ending at the class in question (of that page).

[goneall]

Is the solution to remove the SubclassOf: none or update the spec-parser to handle this case?

[zvr]

spec-parser can generate what is needed.

But what is the desired outcome?

What should be generated in cases where:

• there are no superclasses (e.g. Element)
• there is only one superclass (e.g. Artifact)
• there are more than one (e.g. File)

?

Right now, in all cases, what is being generated is the complete list of classes, ending with (and including) the class in question.

[zvr]

Adding more context, the output has always been like this since we added this functionality 5 months ago.

The way to think about what is presented is a "class hierarchy", if you will, showing "inheritance". But in our spec, we are defining RDF classes, and the words "inheritance" and "hierarchy" are not acceptable in that domain; RDF talks about "superclasses" only.

[zvr]

@goneall any additional input on how you want to see this?

I see you put the 3.1 milestone; are you OK leaving this as it currently is in the PDF to go to ISO? Or do you want to have it reworked / reworded?

Would a section title like "List of classes" or something similar be better?

[goneall]

What should be generated in cases where:

there are no superclasses (e.g. Element)

My current opinion is just using something like "None" to indicate there is no superclass

Alternatives I'm also OK with:

• We could not include the superclass section
• If we want to be RDF specific - we could use owl:Thing as the superclass

there is only one superclass (e.g. Artifact)

I would just have the superclasses - not the class itself (e.g. just Element for Artifact)

there are more than one (e.g. File)

I would include all the hierarchy except the class itself

[goneall]

@goneall any additional input on how you want to see this?

I see you put the 3.1 milestone; are you OK leaving this as it currently is in the PDF to go to ISO? Or do you want to have it reworked / reworded?

I'm OK with fixing this later in 3.1 - I consider it mostly a documentation issue. If someone complains in the ISO review, we can fix it on an update.

Would a section title like "List of classes" or something similar be better?

Now that I think about it, we could just rename the title "Class Hierarchy", then having the class itself in the section would make sense (at least to me) since you can have the class in the hierarchy but it technically isn't a superclass of itself. If we rename it, I wouldn't change anything else.

If we don't include the class itself in the section (as proposed above), the current title is fine.