Hi On Thu, Apr 21, 2011 at 12:35 AM, KARR, DAVID (ATTSI) <[email protected]> wrote: >> -----Original Message----- >> From: Sergey Beryozkin [mailto:[email protected]] >> Sent: Thursday, April 14, 2011 2:26 PM >> To: [email protected] >> Subject: Re: Generate human-readable documentation from WADL? >> >> Yes, I can see this link too: >> https://github.com/mnot/wadl_stylesheets >> >> However we will try to ship our own stylesheet, it's on the map, WADL >> work >> is one the map from now on > > If you do this, consider rendering schema information in a graphical form, > instead of plain text. That means you'd have to have more than just a > stylesheet, but the resulting documentation could be higher quality than what > you'd get with plain text. I'm sure that code to do this could be quite > complex, but I'm going to raise the issue anyway. >
Converting a given XML Schema instance into a proper graphical tree can be a very challenging task, especially if start supporting WADL-first development. Perhaps, initially, we can have a grammar section containing an external link only, which, if clicked, will lead to a pretty printed XML. When I was saying that WADL work was on the map I was implying, should've made it more explicit, that adding a WADL-first code generator was an important task - such a generator can faciliate the development of higher-level tools given that for a WADL-first approach to be more viable, a tool helping create a WADL doc (possibly indirectly) has to be available. Having a good human readable description created from a generated WADL is also an important task, but I'd put it after the code generator task, as far as priorities are concerned. We actually have the WADL-first code generator done - the initial code is there, but it only can be used for auto generating the code on request. That code-generator related code has to be also wrapped by a command-line tool and maven plugin... Cheers, Sergey
