Re: [aerogear-dev] SDK API doc

Worth to mention that there is also alternative aproach when all apis are available together. For example: https://github.com/lord/slate On Thu, Feb 1, 2018 at 3:44 PM, Wojciech Trocki <wtrocki(a)redhat.com&gt; wrote: > Awesome idea to use different tooling. > > We could generate documentation on release (by tooling) and use state of > the art solutions for each platform. > Each platform is different and there are different tools available so > keeping the format may be hard. > > There are plenty of projects that give us this out of the box. Just > couple examples: > > https://github.com/realm/jazzy (ios) > http://typedoc.org/ (TypeScript - cordova) > > Another really good idea mentioned above is to avoid extensive code > examples in documentation by referencing api docs. > We have done that in RainCatcher and it worked really good > > http://raincatcher.feedhenry.io/docs/#_logging (see logger api > documentation) > > This will help us to avoid our documentation getting out of sync with the > actual code. > We could host that on github pages for community. > I think that it will be hard to get into details on mailing list so we > could create proposal for API docs. > > On Thu, Feb 1, 2018 at 3:32 PM, Paul Wright <pwright(a)redhat.com&gt; wrote: > >> Hi, >> >> 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). >> >> 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. >> >> 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 >> >> getSyncClient().list("tasks"); >> >> For more information see <link to android ref docs> >> >> syncClient.listWithDataId("tasks") >> >> For more information see <link to ios ref docs> >> >> >> WDYT? >> >> -- >> Paul Wright >> Mobile Docs (github: finp) >> >> -- >> You received this message because you are subscribed to the Google >> Groups "Aerogear" group. >> To unsubscribe from this group and stop receiving emails from it, send >> an email to aerogear+unsubscribe(a)googlegroups.com. >> To post to this group, send email to aerogear(a)googlegroups.com. >> To view this discussion on the web visit https://groups.google.com/d/ms >> gid/aerogear/5749d108-985c-250a-422c-27fbaa7c3e91%40redhat.com >> <https://groups.google.com/d/msgid/aerogear/5749d108-985c-250a-422c-27fbaa... >> . >> For more options, visit https://groups.google.com/d/optout. >> > > > > -- > > WOJCIECH TROCKI > > Red Hat Mobile <https://www.redhat.com/> > > IM: wtrocki > <https://red.ht/sig> > -- WOJCIECH TROCKI Red Hat Mobile <https://www.redhat.com/> IM: wtrocki <https://red.ht/sig> -- You received this message because you are subscribed to the Google Groups "Aerogear" group. To unsubscribe from this group and stop receiving emails from it, send an email to aerogear+unsubscribe(a)googlegroups.com. To post to this group, send email to aerogear(a)googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/ msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-upe-C5PUvJh0evyJG9Z_LPd1ArQ% 40mail.gmail.com <https://groups.google.com/d/msgid/aerogear/CAO0%2Bn%2BqgokrQtTqd6B1Oab-up... . For more options, visit https://groups.google.com/d/optout.