Clarification: it reads JavaDoc comments, like the standard JavaDoc Doclet.
On Fri, Feb 12, 2016 at 5:26 PM, Stephen Cameron <[email protected] > wrote: > 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 >> >> >> >
