Enhance docs with auto generated UML Class Diagram

Crystal Contrib
1

I’m obsessed with drawings. ER for SQL, Railroad for BNF, FSM drawings. But what about UML for classes?

The UML Class Diagrams are suitable for early design but are impossible to maintain and a bit too fuzzy I think.

(For the record some people are unfamiliar with drawings. No habit, perhaps some dys-drawings…, And frawings are quite rare on forums).

It could be useful at re-factoring, pausing!, exploring, co-operation, support etc.

Now we make software to GENERATE static Uml Class Diagrams for Class Oriented languages like crystal.

Untitled

(Practice: try find the wrong arrow!)

How?

I looked into /doc/index.json using https://github.com/straight-shoota/crystal-api

with the informative models.cr

trying to find relationships between types in general. But I only found inheritances, no references from a property to its type for example.

So I merged that json with an other json holding references for relevant type (explicit references. Not due to require or include

  1. for property and methodparmas and constructors: ref-to-types
  2. for methods: in-body-ref-to-types WHERE THINGS WILL BE RELATED EXPLICTLY
  3. Did nothing on macro types

The output from that step was:

  1. a fine UML Class diagram as .svg
  2. a json later imported in the webbrowser docs/index_uml_class_diagram.html which produced a clickable, zoomable Class Diagram
  3. plans are to produce an other view with each type just as a box but with relationships out/in and with restricted illumination for a type with click

Whorks to do:

  1. Enhance the content in docs/index.json (Tricky one, perhaps other sources, crystal tool hierarchy)
  2. Productify the .svg and .json-for webb
  3. Productify the index_uml_class_diagram.html and some .js (It is static. Need not to be generate at crystal docs

I did some experiments from /doc/index.json using https://github.com/straight-shoota/crystal-api
with the informative models.cr
trying to find relationships between types in general. But I only found inheritances, no references from a property to its type for example

So I merged that json with an other json holding references for relevant type (explicit references. Not due to require or include

  1. for property and methodparmas and constructors: ref-to-types
  2. for methods: `in-body-ref-to-types`` WHERE THINGS WILL BE RELATED EXPLICTLY
  3. Did nothing on macro types

The output from that step was

  1. a fine UML Class diagram as .svg
  2. a json later imported in the webbrowser `docs/index_uml_class_diagram.html`` which produced a clickable, zoomable Class Diagram
  3. plans are to produce an other view with each type just as a box but with relationships out/in and with restricted illumination for a type with click

What to do

  1. Enhance the content in docs/index.json (Tricky one, perhaps other sources, crystal tool hierarchy)
  2. Productify the .svg and .json-for webb
  3. Productify the index_uml_class_diagram.html and some .js (It is static. Need not to be generated at crystal docs time)

Opionons?

4 Likes
2

In my experience, very large diagrams doesn’t help understanding a system. And usually, when I require some understanding of the relations between classes, I’m looking for some particular information (cyclic references, inconsistencies between two modules, etc.). And this is easier to find directly in code than with a humongous diagram.

Perhaps getting smaller diagrams by request and by certain queries might serve better, but that requires some more work.

2 Likes
3

In The output from that step was was a remark 3 which suggested I condensed form wit just small boxes for each type (with no content) but holding references between types.

I think would be useful

/willy

1 Like