Candy Doc is a documentation generator plugin for projects built with the Domain-Driven-Design approach.

"Domain-Driven Design is an approach to software development that centers the development on programming a domain model that has a rich understanding of the processes and rules of a domain." - Martin Fowler See more

• Installation
  • With Maven
• DDD Annotations
  • Aggregate
  • Bounded Context
  • Core Concept
  • Domain Command
  • Domain Event
  • Shared Kernel
  • Value Object
• HTML Documentation 🌐
• ROADMAP 🗺️
• [FOR DEV] Development workflow
  • Release policy
• Technologies
• References
• Join us 🙋
• Contributors ✨

To run this plugin, import the following:

<dependency>
    <groupId>io.candy-doc</groupId>
    <artifactId>candy-doc</artifactId>
    <version>${candy-doc.version}</version>
</dependency>

<plugin>
<groupId>io.candy-doc</groupId>
<artifactId>candy-doc</artifactId>
<version>${candy-doc.version}</version>
<executions>
    <execution>
        <goals>
            <goal>candy-doc</goal>
        </goals>
    </execution>
</executions>
<configuration>
    <packagesToScan>
        <packageToScan>com.foo.bar</packageToScan>
    </packagesToScan>
    <outputFormat>html</outputFormat>
</configuration>
</plugin>

Then, specify the configuration parameters:

packagesToScan: The chosen packages to scan to generate a documentation for.

Example:

<packagesToScan>
    <packageToScan>com.foo.bar.baz</packageToScan>
    <packageToScan>com.foo.qux</packageToScan>
</packagesToScan>

outputFormat: The output format in which the documentation is generated. Output format can be either html, yml or json.

Once your project is correctly annotated with the DDD Annotations, use mvn to run the plugin ( replace ${candy-doc.version} with the current version you are using):

mvn io.candy-doc:candy-doc:${candy-doc.version}:candy-doc

The documentation will be generated in the target/candy-doc directory.

Domain-Driven-Design concepts are identified with annotations.

@Aggregate(name = "", description = "")

Cluster of domain objects that can be treated as a single unit. It has an identity and a lifetime.

An aggregate contains the domain logic and is aware of framework issues.

It is accessed by commands, returns events and deals with value objects.

Value objects in an aggregate are usually seen as Domain entities. This is the only domain model that can be mutable.

@BoundedContext(name = "", description = "")

Set of elements (classes, services, etc) containing only what is needed in a specific context.

Only package-info.java files can be annotated with @BoundedContext. Every other concepts must be inside a bounded context.

@CoreConcept(name = "", description = "")

Concept with the highest level of importance inside a bounded context. It is used in the domain layer, on aggregates and value objects.

A Core Concept can interact with other concepts.

@DomainCommand(description = "")

A command is the entry point to perform a business logic from an aggregate.

It should use primitives only (and could use value objects) and is performed on an aggregate.

@DomainEvent(description = "")

Captures the memory of something interesting which affects the domain. It usually starts with a verb in the past tense.

An event should always stay dumb and only carry static information.

Moreover, domain events cannot use strong domain concepts as domain logic should never be used outside the domain.

@SharedKernel(name = "", description = "")

Set of elements (classes, services, etc) containing only what is needed in a specific context. A shared kernel is the intersection of two bounded contexts (same DDD concepts used in each one). It is often used to describe the relationship between two (or more) teams that share a small but common model. It can only contains value objects and core concepts.

Only package-info.java files can be annotated with @SharedKernel. They work like bounded context do.

@ValueObject(description = "")

An object that has no identity, no lifetime and who is compared based on his values.

A Core Concept can interact with one or more value objects. A Value Object only has primitive fields, is immutable and should be valid when instantiated.

If you have chosen html as output format, you can open the generated index.html file from your file explorer to have access to the documentation.

Navigate between the concepts of your project thanks to the left-side menu

Access the content of each concept

See the interactions between concepts

To know on what the team are actually working on, you can see the different milestones here

The development team works on a branch named main.

Whenever a feature needs to be implemented, a new branch (feat/<new_branch>) must be pulled from main and rebased to this later once the feature is ready.

graph TD
    .. --main--> 1
    1 --> 2
    2 --> 3
    3 --> 4
    1 --feat/my-feature--> 2bis
    2bis --> 3bis
    3bis --> 4bis

Then, we will approve your changes and we will push these changes to main.

Depending on which improvements you will bring to the plugin, you will have to choose the right gitmoji in your PR name in order to publish a new version.

graph TD
    .. --feat/my-feature--> 1
    1 --> 2
    2 --> 3
    3 --> 4
    4 --> 2bis
    2bis --> 3bis
    3bis --> 4bis

Explanations:

Before each new feature, run:

git checkout main
git pull

Create a new branch feat/<branch name> for the feature

git checkout -b feat/<branch name>

Once the feature is implemented, create a pull request to get the approval of a reviewer. If it's approved, your feature will be squash and merge feat/<branch name> to main.

See contributing rules here.

/!\ Don't forget to pull the updated pom.xml once the release job is done. /!\

git pull

Project created with:

• DDD, en vrai pour le développeur (Cyrille Martraire): https://www.youtube.com/watch?v=h3DLKrvp5V8
• DDD (Martin Fowler): https://martinfowler.com/tags/domain%20driven%20design.html
• Summary of a 4 days DDD Training (Thomas Ferro): https://thomasferro.medium.com/summary-of-a-four-days-ddd-training-74103a6d99a1

If you want to get in touch with our community there is a Discord server, join us !

• Contribute to the project

Thanks goes to these wonderful people (emoji key):

Maxime Deroullers 👀	Charles Tacquet 📖 🐛 💻 🔣 🎨 💡 🤔 💬 👀 ⚠️	Edouard CATTEZ 👀	Tiflo 🚇 📖 👀 ✅ 🐛 🤔 🚧 💬 📦	Maji 📖 🤔 👀	Pierre 📖 🚇 👀 📦	François Delbrayelle 📖
AVernholles 📖 💻 🐛 ⚠️ 🤔 👀 💡 🎨 🖋	aginesy 📖 💻 🐛 ⚠️ 🤔 👀 💡 🎨 🖋

This project follows the all-contributors specification. Contributions of any kind welcome!