[
https://issues.apache.org/jira/browse/ISIS-2524?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Daniel Keir Haywood updated ISIS-2524:
--------------------------------------
Description:
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
was:
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>
// ...
}
*
> 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)
