Here is something that is maybe close to what I am thinking of, dbdoclet [1]. It converts JavaDoc to DocBook, I'd then manually edit the DocBook XML to just preserve the user relevent bits which I think will be the first part of the class comment and any comments on public methods and properties that are visible to the user in the viewer.
[1] http://www.dbdoclet.org/ On Fri, Feb 12, 2016 at 4:03 PM, Stephen Cameron <[email protected] > wrote: > Hi all, > > I just added an issue to Jira suggesting enhanced user help documentation > via the F1 key or some other means [1](system user as opposed to system > developer). > > There is a bigger question in my mind about how user documentation gets > created - as a process - that is maybe worthy of discussion. Specifically, > the idea that in an DDD and Naked Objects project such documentation should > be created at the same time that code is written and maybe even be embedded > within code in some way. > > In most projects I see the user documentation (if there is any) as being > relevent to developers, certainly that is the way its done with the Apache > Isis demo projects and Add-ons, where the Github README files are basic > explanations of the functionality and how its acheived in code. So the user > documenation is an initial subset of the developer/maintainer > documentation. Another way to look at it is that the user doccumentation is > useful to explain the models 'ubiquitous language' both to new developers > and to users. > > Maybe there is a way to process the code and embedded comments to generate > user documentation that could actually work in an Apache Isis project, > given the close relationship between class and methods and what the user > sees? > > I see that if you add any tags, not only HTML tags to comments then > Javadoc preserves them, that would suggest that a customised Doclet might > work as a means to achieve this. I like this general idea, given the recent > discussion of adding UML diagrams to Javadoc. Maybe the idea of an specific > Apache Isis Project doclet (or doclets) makes sense? > > You can select a custom doclet in Eclipse, but I have no experience as yet > in creating one. > > On the other hand, people seem happy with Asciidoc, and I will give that a > try in the short term. > > Regards > Steve Cameron > > > [1]https://issues.apache.org/jira/browse/ISIS-1307 > > >
