[
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:
*Auto-detect examples*
As per the ISIS-2524 branch that sketches this out, automatically detect (from
src/test/java) any Xxx_example.java classes and copy over to examples/,
post-process and include using include::example$Xxx_example.adoc[]
*Xrefs to page anchors*
for example, in javadoc this: \{@link ActionLayout#cssClassFa} should
correspond to this: xref:Actionlayout#cssClassfa[].
*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.
*Custom 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:
*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
> 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:
> *Auto-detect examples*
> As per the ISIS-2524 branch that sketches this out, automatically detect
> (from src/test/java) any Xxx_example.java classes and copy over to examples/,
> post-process and include using include::example$Xxx_example.adoc[]
> *Xrefs to page anchors*
> for example, in javadoc this: \{@link ActionLayout#cssClassFa} should
> correspond to this: xref:Actionlayout#cssClassfa[].
> *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.
> *Custom 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)
