wicket-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Martijn Dashorst" <martijn.dasho...@gmail.com>
Subject Re: Reference manual based on javadoc
Date Fri, 05 Oct 2007 18:09:49 GMT
Yes I have considered this, but the problem is that the documentation
is not local to the class at hand. Therefore it again will get out of
date, and furthermore, the examples are not printable.

Martijn

On 10/5/07, John Ray <johnray@newonic.com> wrote:
> Have you considered merging the documentation into the examples app
> where each example has a little bit of documentation? This would create
> a kind of wicket by example manual where you could start at the top with
> Hello World and work your way down. You could also use it as a reference
> manual when doing development. So if you want to create a form just go
> to the form example, read the documentation and then copy the code into
> your application.
>
> The main index page would be similar to the existing example app. My
> only suggestion would be to better organize the examples into sections
> with indents on a single page. That would make it easier to find a
> specific example as you could just search for "border" on the main page
> rather then currently where you have to know it's on the component
> reference page.
>
> For each example you could create a framed HTML page. The top half of
> the page would be the live demo. The bottom half would have a
> TabbedPanel with the first tab containing the documentation for the
> example. The other tabs would have the source code. Being a frame you
> could of course resize the frames to get a bigger view of either the
> live demo at the top or the source code.
>
> One other feature that would be really nice is if you could edit the
> java or html source code of an example. The examples framework would
> then compile the code and redisplay it in the top half of the page. Due
> to security concerns I think this option would only be available when
> the examples are run on a user's local machine. Although it might be
> possible to host this with VMWare. You'd have to pass off custom code to
> java running inside of VMWare then monitor the JVM through the debugger
> interface and kill the JVM if the user spawns threads, has a while loop
> then never exits, etc.
>
> John
>
>
> Martijn Dashorst wrote:
> > All,
> >
> > We all know we suck at writing docs, even though we have several book
> > authors in our midst.
> >
> > There are some problems I see with maintaining a separate reference manual:
> >  - base format -> docbook is a nasty piece of work to write, latex is
> > somewhat better, word is not multi-user
> >  - recency -> the docs are pretty soon outdated.
> >
> > If we are able to get a single point of definition, then that would be
> > a killer IMO.
> >
> > It should be possible to generate a reference manual based on our
> > javadocs. If the descriptions for classes are written correctly we
> > only have to maintain the javadocs, and generate a pdf and website
> > based on that.
> >
> > We don't have to generate the document for *all* classes, we can
> > create a ToC based on whatever classes we wish to include, and group
> > them in everyway we see fit. With maybe some extra javadoc annotations
> > we will be able to select particular methods that are of interest for
> > the reference manual, whilst ignoring the rest of them.
> >
> > There are several doclets that allow you to generate PDF's, latex or
> > docbook as an output format. http://doclet.com is the cannonical list.
> >
> > What do others think?
> >
> > Martijn
> >
> >
>
>


-- 
Buy Wicket in Action: http://manning.com/dashorst
Apache Wicket 1.3.0-beta3 is released
Get it now: http://www.apache.org/dyn/closer.cgi/wicket/1.3.0-beta3/

Mime
View raw message