PlantUML: nested components with text possible?

Question

As I've seen from the examples in PlantUML you can have certain graphical objects with text in it like

folder folder1 [
    Here you can have some explanation with
    ====
    --Markdown-- //formatting// ~~elements~~
]

which renders to

You can also use folder (among other elements) to group other items by nesting them:

folder folder2 {
    folder folder3 [
        text bla bla
    ]
    artifact art2 [
        more text
    ]
}

But currently I see no way to combine both - an object with some explaining text in it and nested elements.

Is that possible with PlantUML? (how?)

Answer 1

I can only assume that PlantUML tries to be as UML-like as possible. While it is possible to add long descriptions ([...]) to elements, I'm almost certain it was intended only for certain element types (e.g. activity elements, use cases, etc.), which generally do not contain sub-elements. However, for more formal diagrams, any "text" required to annotate or further explain a concept should be added as notes or callouts.

I ran into this issue many moons ago, and did do exactly as you are trying to do. I dug into my diagram archives and found an example that would be very close to what you want to achieve.

Thus, to answer your question, a solution for including both descriptive text and UML elements in a grouping elements such as folders, is as follows:

@startuml
skinparam rectangle<<desc>> {
    backgroundColor Transparent
    borderColor Transparent
    titleFontColor Red
    stereotypeFontColor Transparent
}

folder folder2 {
    folder folder3 [
        text bla bla
    ]
    artifact art2 [
        more text
    ]
    rectangle f2<<desc>> [
        Here you can have some explanation with
        ====
        --Markdown-- //formatting// ~~elements~~
    ]

    folder3 -[hidden]- f2
}
@enduml

As you will note, a connection is used to tweak text placement and may require some more complex finagling depends on the size of your text and the number of elements.

Since those early days, I have followed closer to the UML spec; see this answer for more details on comments. Not only is it easier to add comments, but PlantUML code is far simpler. That said, the following is a variant of the above using this approach.

@startuml
folder folder2 {
    folder folder3 [
        text bla bla
    ]
    artifact art2 [
        more text
    ]
}

note bottom of folder2
    Here you can have some explanation with
    ====
    --Markdown-- //formatting// ~~elements~~
end note
@enduml