<div dir="ltr">Awesome idea to use different tooling. <div><br>We could generate documentation on release (by tooling) and use state of the art solutions for each platform.</div><div>Each platform is different and there are different tools available so keeping the format may be hard.<br></div><div><br></div><div>There are plenty of projects that give us this out of the box. Just couple examples:</div><div><br></div><div><a href="https://github.com/realm/jazzy" target="_blank">https://github.com/realm/jazzy</a> (ios)<br></div><div><a href="http://typedoc.org/" target="_blank">http://typedoc.org/</a> (TypeScript - cordova)<br></div><div><br></div><div>Another really good idea mentioned above is to avoid extensive code examples in documentation by referencing api docs.</div><div>We have done that in RainCatcher and it worked really good</div><div><br></div><div><a href="http://raincatcher.feedhenry.io/docs/#_logging" target="_blank">http://raincatcher.feedhenry.<wbr>io/docs/#_logging</a> (see logger api documentation)<br></div><div><br></div><div>This will help us to avoid our documentation getting out of sync with the actual code. </div><div>We could host that on github pages for community.</div><div>I think that it will be hard to get into details on mailing list so we could create proposal for API docs.</div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Feb 1, 2018 at 3:32 PM, Paul Wright <span dir="ltr"><<a href="mailto:pwright@redhat.com" target="_blank">pwright@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF">
<p>Hi,</p>
<p>There is existing tooling to generate API reference doc for
Android and iOS. I'm thinking we should use that to generate
comprehensive API doc for both platforms (and later for Cordova).
<br>
</p>
<p>I believe this gives the best experience to the <platform>
developer, on the basis that, at any one time, they developer is
working on a single platform (and typically a colleague is
developing the 'other' platform). The disadvantages of this
approach include the fact that the appearance of generic
docs/android/ios will all be different, but we can put enough
navigation into the html to allow users enter and exit this
reference without too much pain.<br>
</p>
<p>However there is also a requirement to show the cross platform
nature of mobile-next, to demonstrate the generic nature of a
particular call. I'd like to address this, not in the 'full' API
docs, but in examples of typical use cases which might look like <br>
</p>
<pre class="m_196875409478135777m_-3618962948987576115programlisting m_196875409478135777m_-3618962948987576115language-java" style="box-sizing:border-box;overflow:auto;font-family:Consolas,Monaco,"Andale Mono",monospace;font-size:13px;display:block;padding:0.9375rem;margin:0px 0px 1.8em;line-height:1.5;word-break:normal;word-wrap:normal;color:rgb(240,240,240);background:rgb(37,37,37);border:1px solid rgb(26,26,26);border-radius:0px;white-space:pre!important;direction:ltr;text-align:left;word-spacing:0px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;text-decoration-style:initial;text-decoration-color:initial"><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">getSyncClient</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">(</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">.</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">list</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">(</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115string" style="box-sizing:border-box;color:rgb(150,203,228);padding-left:0px;background:none">"tasks"</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">;</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none"></span></pre>
<p>For more information see <link to android ref docs></p>
<pre class="m_196875409478135777m_-3618962948987576115programlisting m_196875409478135777m_-3618962948987576115language-swift" style="box-sizing:border-box;overflow:auto;font-family:Consolas,Monaco,"Andale Mono",monospace;font-size:13px;display:block;padding:0.9375rem;margin:0px 0px 1.8em;line-height:1.5;word-break:normal;word-wrap:normal;color:rgb(240,240,240);background:rgb(37,37,37);border:1px solid rgb(26,26,26);border-radius:0px;white-space:pre!important;direction:ltr;text-align:left;word-spacing:0px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;text-decoration-style:initial;text-decoration-color:initial">syncClient<span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">.</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115function" style="box-sizing:border-box;color:rgb(183,230,178);padding-left:0px;background:none">listWithDataId</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">("tas<wbr>ks"</span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115constant" style="box-sizing:border-box;color:rgb(220,103,94);padding-left:0px;background:none"></span><span class="m_196875409478135777m_-3618962948987576115token m_196875409478135777m_-3618962948987576115punctuation" style="box-sizing:border-box;color:rgb(153,153,153);padding-left:0px;background:none">)
</span></pre>
For more information see <link to ios ref docs><br>
<br>
<br>
WDYT?<span class="m_196875409478135777HOEnZb"><font color="#888888"><br>
<pre class="m_196875409478135777m_-3618962948987576115moz-signature" cols="72">--
Paul Wright
Mobile Docs (github: finp)</pre>
</font></span></div><span class="m_196875409478135777HOEnZb"><font color="#888888">
<p></p>
-- <br>
You received this message because you are subscribed to the Google Groups "Aerogear" group.<br>
To unsubscribe from this group and stop receiving emails from it, send an email to <a href="mailto:aerogear+unsubscribe@googlegroups.com" target="_blank">aerogear+unsubscribe@googlegro<wbr>ups.com</a>.<br>
To post to this group, send email to <a href="mailto:aerogear@googlegroups.com" target="_blank">aerogear@googlegroups.com</a>.<br>
To view this discussion on the web visit <a href="https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com?utm_medium=email&utm_source=footer" target="_blank">https://groups.google.com/d/ms<wbr>gid/aerogear/5749d108-985c-250<wbr>a-422c-27fbaa7c3e91%40redhat.<wbr>com</a>.<br>
For more options, visit <a href="https://groups.google.com/d/optout" target="_blank">https://groups.google.com/d/op<wbr>tout</a>.<br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="m_196875409478135777gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div style="font-size:12.8px"><p style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-weight:bold;margin:0px;padding:0px;font-size:14px;text-transform:uppercase"><span>WOJCIECH</span> <span>TROCKI</span></p><p style="font-family:overpass,sans-serif;margin:0px;font-size:10px;color:rgb(153,153,153)"><a href="https://www.redhat.com/" style="color:rgb(0,136,206);margin:0px;text-decoration:none" target="_blank">Red Hat <span>Mobile</span></a></p><p style="font-family:overpass,sans-serif;margin:0px 0px 6px;font-size:10px;color:rgb(153,153,153)"><span>IM: <span>wtrocki</span></span></p><table border="0" style="color:rgb(0,0,0);font-family:overpass,sans-serif;font-size:medium"><tbody><tr><td width="100px"><a href="https://red.ht/sig" target="_blank"><img src="https://www.redhat.com/files/brand/email/sig-redhat.png" width="90" height="auto"></a></td></tr></tbody></table></div></div></div></div></div></div></div></div></div>
</div></div>