<html><head></head><body bgcolor="#FFFFFF"><div>That's exactly what I'm poking at (and what Nati has started doing as well). I was trying to see if there was a consistent way to describe all the API endpoints that could be used to document the combined set.</div><div><br></div><div>The raw description is clearly insufficient, so how best to create a final product that has that information. My original question was towards can we embed that additional information in the API description and render it into final form, or do we just "bag it" and manage all of that detail by hand (in restructuredtext, docbook, etc)<br><br>-joe</div><div><br>On Oct 25, 2011, at 3:34 PM, Caitlin Bestler <<a href="mailto:Caitlin.Bestler@nexenta.com">Caitlin.Bestler@nexenta.com</a>> wrote:<br></div><div></div><blockquote type="cite"><div>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="Generator" content="Microsoft Word 14 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle18
{mso-style-type:personal-reply;
font-family:"Calibri","sans-serif";
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">WADL sounds like a wonderful validation tool.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">But shouldn’t our primary goal be finding a consistent way to describe the APIs<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">for *<b>application developers</b>*.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Syntax tools, whether ancient notations like BNF or the latest XML concoction only tell you the syntax of the operation.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">There also has to be consistent information that provides information to the reader as to when and why they would use<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">this specific operation, not just how to format it.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">There is also a tendency of syntax oriented tools to omit vital state information, particularly the expected sequence of operations.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
</div>
</div></blockquote><blockquote type="cite"><div><span>_______________________________________________</span><br><span>Mailing list: <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a></span><br><span>Post to : <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a></span><br><span>Unsubscribe : <a href="https://launchpad.net/~openstack">https://launchpad.net/~openstack</a></span><br><span>More help : <a href="https://help.launchpad.net/ListHelp">https://help.launchpad.net/ListHelp</a></span><br></div></blockquote></body></html>