[
https://issues.apache.org/jira/browse/ISIS-2524?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17278582#comment-17278582
]
Andi Huber commented on ISIS-2524:
----------------------------------
+1 ... details to be discussed
> Tooling: Ideas to enhance 'projdoc' support
> -------------------------------------------
>
> Key: ISIS-2524
> URL: https://issues.apache.org/jira/browse/ISIS-2524
> Project: Isis
> Issue Type: Improvement
> Affects Versions: 2.0.0-M5
> Reporter: Daniel Keir Haywood
> Priority: Major
> Fix For: 2.0.0-M6
>
>
> in adopting the 'projdoc' global index, I've commented out some existing
> material. It'd be nice to have that material in the source code and projdoc
> generate pages the way I'd like them.
> Several ideas:
> *Separate pages*
> for annotations, to split out annotation elements (eg @Action#semanticsOf) as
> separate pages/sections; then they will have a bookmark anchor on a page that
> can be hyperlinked to.
> *Asciidoclet*
> to allow richer text, to allow comments to be written in Asciidoc. This
> would leverage the existing asciidoclet doclet in our CI
> ([https://github.com/asciidoctor/asciidoclet#example),] while users of
> IntelliJ could also benefit from asciidoclet plugin support
> ([https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoclet.html).|https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoclet.html)]
> If that is unwieldy, then perhaps simply allow .adoc comments to be stored
> alongside the .java files (similar to our layout files) and have projdoc
> stitch it all together.
> For example, the extended material for @Action#semanticsOf element would
> reside in Action#semanticsOf.adoc, right alongside Action.java.
> *Sections*
> to provide a syntax where regions are effectively supported. This could be
> done perhaps by a tag (similar to \{@index} in the comment of members.
> For example, the original documentation for @DomainObject - currently
> commented out - had sections that explained the elements that made up
> lifecycleEvents, and then another for domainEvents. It would be nice if
> these sections could be declared by for example an \{@index
> section="Lifecycle Events"} or similar in the comment of each method to be
> included in that section.
> I am thinking that the outer class would also be rendered, ie something like:
> {code:java}
> public @interface DomainObject {
> // ...
> Class<? extends ObjectCreatedEvent<?>> createdLifecycleEvent() default
> ObjectCreatedEvent.Default.class; // <.>
> Class<? extends ObjectPersistingEvent<?>> persistingLifecycleEvent()
> default ObjectPersistingEvent.Default.class; // <.>
> <and the remaining methods in this section>
> // ...
> } {code}
> *Xxx*
> xxx
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
