Mailing-List: contact users-help@cxf.apache.org; run by ezmlm
Precedence: bulk
Reply-To: users@cxf.apache.org
Received-SPF: pass (nike.apache.org: domain of sberyozkin@gmail.com designates
 209.85.214.41 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=AhDkH6nG4RKPx/A8YQqqqsSUN3Axa/iAw1kEQOr9UKP5thyfSIE4mAYC7RLWCt1ge7
         3d2POjWTsdIir5YRL0ubTMWfcPQEd/CNoYHlqxBhQ/OW9GG/tulCzHFHwveWuZIw/BO7
         iCY75w+nYqWU9qMgmGK8UI26vM+PjFiRclIwg=
MIME-Version: 1.0
In-Reply-To: 
 <B8D164BED956C5439875951895CB4B2203AADA@WABOTH9MSGUSR8C.ITServices.sbc.com>
References: 
 <B8D164BED956C5439875951895CB4B22035006@WABOTH9MSGUSR8C.ITServices.sbc.com>
	<BANLkTiko2UeGWBdmZ+tybmL0daLnyrryvQ@mail.gmail.com>
	<B8D164BED956C5439875951895CB4B2203AADA@WABOTH9MSGUSR8C.ITServices.sbc.com>
Date: Thu, 21 Apr 2011 12:01:29 +0100
Message-ID: <BANLkTinruAa7HAiRgrPjPT20kPteH4mtvA@mail.gmail.com>
Subject: Re: Generate human-readable documentation from WADL?
From: Sergey Beryozkin <sberyozkin@gmail.com>
To: users@cxf.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

Hi

On Thu, Apr 21, 2011 at 12:35 AM, KARR, DAVID (ATTSI) <dk068x@att.com> wrot=
e:
>> -----Original Message-----
>> From: Sergey Beryozkin [mailto:sberyozkin@gmail.com]
>> Sent: Thursday, April 14, 2011 2:26 PM
>> To: users@cxf.apache.org
>> 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. =A0That means you'd have to have more than just a =
stylesheet, but the resulting documentation could be higher quality than wh=
at you'd get with plain text. =A0I'm sure that code to do this could be qui=
te 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