[jira] [Updated] (ISIS-2524) Tooling: Ideas to enhance 'projdoc' support

["Daniel Keir Haywood (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/ISIS-2524?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Daniel Keir Haywood updated ISIS-2524:
--------------------------------------
    Summary: Tooling: Ideas to enhance 'projdoc' support  (was: Ideas to enhance 'projdoc' support)

> 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:
>  * 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)