Daniel Keir Haywood created ISIS-2524:
-----------------------------------------
Summary: 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
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:
* 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.
* 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)]
* 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:
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>
// ...
}
*
--
This message was sent by Atlassian Jira
(v8.3.4#803005)
