Enhancement: Render Header/Title and/or Legend

[Justin-W]

It'd be very helpful if the rendered puml diagram included a diagram title and/or a diagram-level legend (maybe a puml note?) with info about the diagram.

Optionally, 1+ new CLI flag could be added to disable the title, legend, etc. (in full and/or in part).

Suggested Diagram Metadata

• Diagram Title E.g. Something related to the target golang package's full import path.
• Render-time info (e.g. date/time rendered)
• Rendering options E.g. Indicating any non-default rendering options were used to render the diagram (but possibly excluding any self-evident options, such as -label-edges).
• (optionally) Git-related info (e.g. git branch that was rendered)

Rationale

When generating multiple diagrams (for different packages, or for the same package but with different CLI options, such as with and without -recursive or -hide-fields), the diagrams' contents are currently ambiguous, because they don't indicate whether content (subpackages, edges, fields, etc.) that is missing from the diagram is missing because of goplantuml CLI options, or because of the underlying package's source code.

With the above items included (automatically by default or via optional CLI flag) in each diagram's rendered content, the generated diagram's content would be self-documenting, unambiguous, and useful as a standalone design or review artifact.

Also, having goplantuml render the Title, Legend, etc. would prevent the need for post-rendering manual addition of such info, and also allow goplantuml to retain control over the formatting and content of the Title and Legend (e.g. when a new CLI flag is added to goplantuml, you would be able to decide what effect, if any, it should have on the Title and Legend).

However, retaining the ability to disable/hide the Title, Legend, etc. would be good, since it would allow generated diagrams to be included in documents, web pages, etc. which might want to control captions, titles, etc. separately from the diagram's image file.

[jfeliu007]

This is an interesting proposition. I will make it so that you can pass Notes and a title to the parser as options. However, it will be up to the CLI to properly construct the notes (in this case the legend and the title. As for the git branch. I believe this goes beyond the intended functionality of this library since git is one of the source control available. Now with the implementation of notes, there is nothing stopping you from passing the git branch name as one of the notes. :)

[jfeliu007]

I am finding that notes are a little irresponsible when not attached to certain elements. That means we do not know where they render. Therefore, I am implementing this for now with a Legend tag. Unfortunately Plantuml only accepts one legend per diagram. It will be placed at the bottom center, though, so I think it would be nice to combine any notes you pass with the legend in one legend note.

[Justin-W]

Now with the implementation of notes, there is nothing stopping you from passing the git branch name as one of the notes

A very reasonable decision.

[Justin-W]

I am finding that notes are a little irresponsible when not attached to certain elements. That means we do not know where they render.

IIRC, that is partly true. However, it can be mitigated in certain types of PlantUML diagrams by placing the note before or after certain graph-level elements. E.g. A Title, Legend, and certain keywords (e.g. next to astart or end keyword in activity diagrams).

So the location where you render the note(s) can affect the note position and graph layout.

That might be useful info in case you do decide to use notes (for this issue or for anything else).

[Justin-W]

One other idea: If you were to render some additional, static comments in the output, such as ''' --- CLASSES --- ''', ''' --- ALIASES --- ''', etc. (or some similar, predictably-unique variant), they could act as landmarks or markers that could be used to perform additional post-rendering processing of the output. E.g. To inject a section of PUML code just before a certain subsection of the output, or to do a global regex replace on only 1 'section' of the output.

Without such 'landmark' comments in the output, any post-processing of the output would have to rely on either internal goplantuml implementation details (bad idea) and/or use of target-specific output (e.g. use of target-specific keywords).

But with landmarks included, a variety of additional post-processing options become feasible (e.g. via grep, sed, etc.). Possibly including post-rendering injection of additional notes, etc. independent of the goplantuml CLI (although I think CLI flags for certain basic things are still a good idea).

[jfeliu007]

One other idea: If you were to render some additional, static comments in the output, such as ''' --- CLASSES --- ''', ''' --- ALIASES --- ''', etc. (or some similar, predictably-unique variant), they could act as landmarks or markers that could be used to perform additional post-rendering processing of the output. E.g. To inject a section of PUML code just before a certain subsection of the output, or to do a global regex replace on only 1 'section' of the output.

Without such 'landmark' comments in the output, any post-processing of the output would have to rely on either internal goplantuml implementation details (bad idea) and/or use of target-specific output (e.g. use of target-specific keywords).

But with landmarks included, a variety of additional post-processing options become feasible (e.g. via grep, sed, etc.). Possibly including post-rendering injection of additional notes, etc. independent of the goplantuml CLI (although I think CLI flags for certain basic things are still a good idea).

I will consider this as a separate issue.