[aerogear-dev] SDK API doc

[Wojciech Trocki]

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 at redhat.com> 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 at googlegroups.com.
> To post to this group, send email to aerogear at 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-27fbaa7c3e91%40redhat.com?utm_medium=email&utm_source=footer>
> .
> 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>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20180201/65dd3bf4/attachment.html