[aerogear-dev] iOS API Doc improvement

Matthias Wessendorf matzew at apache.org
Fri Mar 8 03:55:55 EST 2013


let's wait a bit, I actually think it's a bit unordered to have
everything on top of the file.

Imagine you end up with 30 functions - do you really want all the doc
at the beginning ?

Hrm...

On Fri, Mar 8, 2013 at 8:59 AM, Christos Vasilakis <cvasilak at gmail.com> wrote:
> I think (for now)  will go ahead with option 3, having the examples and explanation on top of the Class reference, but we can certainly revisit later on.
>
> Thanks!
> Christos
>
> On Mar 7, 2013, at 8:47 PM, Douglas Campos <qmx at qmx.me> wrote:
>
>> I'm 50-50 between 3 and 4 - 3 is nice for newcomers, who can see the examples right away, 4 is nice for reference.
>>
>> Tough call do decide :(
>>
>> On 07/03/2013, at 13:31, Matthias Wessendorf <matzew at apache.org> wrote:
>>
>>> I am not sure;
>>>
>>> having the snippets on top of the functions where they belong too, makes sense;
>>>
>>> Having EVERYTHING at the begining of the file is, perhaps, nice for
>>> some folks too...
>>>
>>> I think I'd be +0.5 for the [4]
>>>
>>> -M
>>>
>>> On Thu, Mar 7, 2013 at 3:57 PM, Christos Vasilakis <cvasilak at gmail.com> wrote:
>>>> Hi team,
>>>>
>>>> we are currently in the process of cleaning up and improving iOS documentation. For better visibility, we are integrating the API usage guide found here [1] inside (generated from code) API docs [2].
>>>>
>>>> The question is where we should put the "example code". For this, there are two approaches, either collect and put them all in the header of the file with different sections[3]  or inline with the function [4].
>>>>
>>>> wdyt?
>>>>
>>>> -
>>>> Christos
>>>>
>>>> [1] https://github.com/aerogear/aerogear-ios/blob/master/API.md
>>>> [2] http://aerogear.org/docs/specs/aerogear-ios/
>>>> [3] http://tinyurl.com/cdldzh9
>>>> [4] http://tinyurl.com/cjhg5ke
>>>>
>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> aerogear-dev mailing list
>>>> aerogear-dev at lists.jboss.org
>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>>
>>>
>>>
>>> --
>>> Matthias Wessendorf
>>>
>>> blog: http://matthiaswessendorf.wordpress.com/
>>> sessions: http://www.slideshare.net/mwessendorf
>>> twitter: http://twitter.com/mwessendorf
>>> _______________________________________________
>>> aerogear-dev mailing list
>>> aerogear-dev at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>>
>> -- qmx
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev



-- 
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf


More information about the aerogear-dev mailing list