Docstrings

[IllustratedMan-code]

Proposal

I think it would be great to add the ability to get the docstrings for classes and or methods and insert them into the uml. This would go a long way in clarifying what classes are actually for in the uml.

Solution

The __doc__ attribute can be used to get the docstrings without much trouble.

[lucsorel]

yes, this could be an interesting feature to add. Module-level docstrings could also be handled.

However, docstrings can be rather verbose and including them in the resulting PlantUML diagram could be optional, what do you think?

Also, could you provide some suggestions about the way docstring would be included and rendered in a PlantUML diagram, please? That would help guiding the development of this feature. Some links like http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000 would suffice.

[grayfox88]

The purpose of a UML class diagram is to provide an overview of a system of classes (defined by their attributes and methods) and their relationships. It is not meant to be used as verbose documentation, so I do not see personally where the docstring content would fit in a UML diagram. As asked by @lucsorel , could you provide an example of what you want to achieve?

[TheDeafOne]

The purpose of a UML class diagram is to provide an overview of a system of classes (defined by their attributes and methods) and their relationships. It is not meant to be used as verbose documentation, so I do not see personally where the docstring content would fit in a UML diagram. As asked by @lucsorel , could you provide an example of what you want to achieve?

I agree in that UML diagrams are generally meant for displaying the system's classes, but for those who might want to use this as more documentation method, it still might be reasonable to have. This could be edging towards something closer to sphinx's auto-documentation at that point. imo it would be useful to have as an optional argument at least

[IllustratedMan-code]

@lucsorel Thanks for the interest!

Sorry this took so long, but here is an example: http://www.plantuml.com/plantuml/uml/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000. Its not perfect, but I think it looks like a good start. Definitely think it should be optional/configurable. Method docstrings can get pretty long, so I think there should be a separate switch for class and method docstrings.

For my particular use case, I work with a lot of developers who are not formally trained (UML is a bit of a foreign concept), so additional details make the diagrams much more understandable for my audience.

[lucsorel]

Thank you @IllustratedMan-code for the example.

Unfortunately, the link you provided does not lead to the UML diagram shown in the screenshot :disappointed:

Would you have some time to rewrite it, then click twice on the dark-mode switch (see the screen shot below): it would update the URL appropriately and you could share it with me.

I have a couple of more burning issues to solve or to finalize before eventually working on this one. Including the raw docstring may not be enough, some people add some markdown formatting, other ones some html formatting, and PlantUML has its own formatting syntax; I am thus not very enthusiastic to work on this feature request alone.