Skip to content

[DOCS] Regenerate the class diagram in the README #1298

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

oliverklee
Copy link
Collaborator

The class diagram is (almost) unchanged to the output from tasuku43/mermaid-class-diagram, except for the kept direction LR.

This is in preparation for adding a script for auto-creating the class diagram in #1297.

@oliverklee oliverklee requested review from sabberworm and JakeQZ June 29, 2025 14:53
@oliverklee oliverklee self-assigned this Jun 29, 2025
@oliverklee oliverklee added documentation developer-specific Issues that only affect maintainers, contributors, and people submitting PRs labels Jun 29, 2025
@coveralls
Copy link

coveralls commented Jun 29, 2025

Coverage Status

coverage: 57.935%. remained the same
when pulling 0632a8d on docs/update-class-diagram
into 6dec68e on main.

@oliverklee oliverklee marked this pull request as draft June 29, 2025 14:56
@oliverklee
Copy link
Collaborator Author

Marking this as draft for now. I'll first reorder the classes in the diagram to make this PR here a bit smaller.

@JakeQZ
Copy link
Collaborator

JakeQZ commented Jun 30, 2025

It would be nice if the diagram had fewer criss-crossing paths. AI should be good at that, but seems to be vastly overrated :/

@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from dff73f2 to c2891db Compare June 30, 2025 13:53
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from c2891db to 207d21e Compare July 2, 2025 14:15
@oliverklee oliverklee marked this pull request as ready for review July 2, 2025 14:16
@oliverklee oliverklee requested a review from JakeQZ July 2, 2025 14:16
Copy link
Collaborator

@JakeQZ JakeQZ left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous source for the diagram had entries like

URL --> "1" CSSString: url

whereas now we have

URL ..> CSSString: dependency

So we no longer identify the property that has the dependency (or whether it's as a single object, array, or whatever). Is there any reason for this change?

@oliverklee
Copy link
Collaborator Author

So we no longer identify the property that has the dependency (or whether it's as a single object, array, or whatever). Is there any reason for this change?

The old version of the generator which we used did not recognize associations at all. That's why I manually added those to the diagram, including the name of the corresponding property.

The current version of the generator does recognize associations, even though it only labels them as "dependency", but not with the name of the corresponding property.

Copy link
Collaborator

@JakeQZ JakeQZ left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I spent a bit of time reordering the original 'relationships' section, after changing to the now-generated syntax, to conclude that there a quite a few differences there.

I think this needs three separate pre-patches so the diffs can be more clearly seen (along the lines of #1299):

  1. Move class URL to be ASCII-sorted;
  2. Change to use ..>, dependency and remove "*"/"1";
  3. Reorder the relationships to be consistent with the generated order.

For reference, what I did for reviewing is on the branch at https://github.com/MyIntervals/PHP-CSS-Parser/tree/docs/class-diagram-review and includes all three of the above, which need to be split. And I may have made mistakes: there was a lot of cutting and pasting

@oliverklee
Copy link
Collaborator Author

I think this needs three separate pre-patches so the diffs can be more clearly seen

Makes sense, will do.

@oliverklee oliverklee marked this pull request as draft July 4, 2025 13:12
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch 4 times, most recently from d98dc23 to adeb8fb Compare July 4, 2025 15:01
oliverklee added a commit that referenced this pull request Jul 5, 2025
oliverklee added a commit that referenced this pull request Jul 5, 2025
oliverklee added a commit that referenced this pull request Jul 7, 2025
JakeQZ pushed a commit that referenced this pull request Jul 7, 2025
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from 8632f7d to fe66e2d Compare July 7, 2025 17:52
oliverklee added a commit that referenced this pull request Jul 7, 2025
JakeQZ pushed a commit that referenced this pull request Jul 7, 2025
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from fe66e2d to be15675 Compare July 7, 2025 18:07
oliverklee added a commit that referenced this pull request Jul 7, 2025
JakeQZ pushed a commit that referenced this pull request Jul 7, 2025
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from be15675 to a775112 Compare July 7, 2025 19:19
oliverklee added a commit that referenced this pull request Jul 7, 2025
JakeQZ pushed a commit that referenced this pull request Jul 7, 2025
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from a775112 to 54eef10 Compare July 7, 2025 20:47
oliverklee added a commit that referenced this pull request Jul 7, 2025
oliverklee added a commit that referenced this pull request Jul 7, 2025
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from 54eef10 to 052484e Compare July 7, 2025 21:07
oliverklee added a commit that referenced this pull request Jul 7, 2025
JakeQZ pushed a commit that referenced this pull request Jul 7, 2025
The class diagram is (almost) unchanged to the output
from `tasuku43/mermaid-class-diagram`, except for the
kept `direction LR`.

This is in preparation for adding a script for auto-creating
the class diagram in #1297.
@oliverklee oliverklee force-pushed the docs/update-class-diagram branch from 052484e to 0632a8d Compare July 8, 2025 08:01
@oliverklee oliverklee marked this pull request as ready for review July 8, 2025 08:02
@oliverklee oliverklee requested a review from JakeQZ July 8, 2025 08:02
Copy link
Collaborator

@JakeQZ JakeQZ left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like it's adding all dependencies, even if they are only passed as method parameters, and not actually stored in class properties. This rather clutters the class diagram. The current one is reasonably easy to understand. The diagram after this change harder to understand and about three times the size.

Would it be possible to exclude dependencies that are only ever used as method parameters?

There seems to be a bug in that traits are completely ignored.

AtRule <|.. AtRuleSet: realization
AtRuleSet ..> OutputFormat: dependency
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it's now also picking up dependencies that are method parameters, not just properties.

Value <|-- ValueList: inheritance

CSSList ..> CSSList: dependency
CSSList ..> Comment: dependency
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like it's losing dependencies that are class properties via traits. The CommentContainer trait was added for classes that have Comments. Given that traits are not included in the class diagram, this looks to me like a bug in the generator (for which I think the better fix would be to include traits in their own right, like interfaces and classes).

OutputFormat ..> OutputFormat: dependency
Rule ..> Comment: dependency
RuleSet ..> Comment: dependency
ValueList ..> Value: dependency
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ValueList extents Value and also has Values as properties. It looks like the latter connection is being lost.

@oliverklee
Copy link
Collaborator Author

Okay, putting this on the backburner until the diagram generator has these two bugfixes/features.

I've created two tickets for that:

@oliverklee oliverklee marked this pull request as draft July 9, 2025 12:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
developer-specific Issues that only affect maintainers, contributors, and people submitting PRs documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants