search

SeedSigner / seedsigner

Use an air-gapped Raspberry Pi Zero to sign for Bitcoin transactions! (and do other cool stuff)
MIT License
658 stars 151 forks source link

Class diagrams UML documentation #271

Open rserranon opened 1 year ago

rserranon commented 1 year ago

I'm a visual learner and while studying the code I generated a model in Gaphor.org (open source UML modeling tool). Gaphor is written in python, is multiplatform, and is lightweight. The models try to cover the most important classes, attributes, and methods needed to make it easier to understand the code base. It could be useful for newcomers to grasp a general understanding or for developers to discuss refactors and new major changes.

The model that Gaphor generates is a simple XML that can be committed to the repo.

Would you be interested if I open a pull request to upload the model and the SVG or PNG diagrams generated to complement the actual documentation?

Here is an example of some of the diagrams I created (you have to click on the diagram to view it in full screen):

Singleton-Controller

Screen hierarchy

jdlcdl commented 1 year ago

I'd be interested in seeing more diagrams. Does the lower-left section of the Singleton-Controller diagram hint of the "# import here to avoid circular imports" hazard? btw: I noticed Controller attribute typos: settingd or settings? screenSaver or screensaver?

added... Binary images in the repo? Not so sure. Maybe a better fit in another "meta" repo of the code repo? Like where automated docs might be built, or at least in the integration/release flow? I'd find it helpful to see these run against older releases, around major refactorings to answer "Where we are and how we got here."

newtonick commented 1 year ago

I like the idea and not opposed. Keeping it updated as code changes are made would be the challenge long term.

kdmukai commented 1 year ago

Concept ACK.

This would definitely be useful, though caveat with Nick's point above.

It looks like there are a few errors in the class names ("DireDrawingScreen" is actually "DireWarningScreen"; there's a "ListList" that's connected to the "BackStack").

Is it fully auto-generated or are there some manual steps? Django, for example, has a similar built-in method for generating similar relationships for its Model classes, but it's 100% automated.

If it isn't fully automated, how automated could it get in order to reduce human error and manual maintenance?

Also, view this PR with github in dark mode. The transparent background of the rendered diagrams is a problem.