put them all in the header of the file with different sections[3

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(a)gmail.com&gt; 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(a)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(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

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(a)qmx.me&gt; 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(a)apache.org&gt; 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(a)gmail.com&gt; 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(a)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(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/aerogear-dev > > -- qmx > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

On Mar 8, 2013, at 3:55 AM, Matthias Wessendorf wrote: > 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 ? Yeah I agree, this is where #4 is nice because the links can take you quickly to the definitions that can then had the code. The trick would be where to put example code that is more complex or mixes function calls. > > Hrm... > > On Fri, Mar 8, 2013 at 8:59 AM, Christos Vasilakis <cvasilak(a)gmail.com&gt; 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(a)qmx.me&gt; 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(a)apache.org&gt; 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(a)gmail.com&gt; 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(a)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(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>> >>> -- qmx >>> >>> >>> _______________________________________________ >>> aerogear-dev mailing list >>> aerogear-dev(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

Hi there, I looked around API documentations for some projects, In general I think it is acceptable on the class description to have some kind of *basic concepts* explained, as in our situation where we have crud,authentication etc operations together with a small example. For example http://tinyurl.com/dy3nxvu or here: http://tinyurl.com/cvzo9tc I am happy to remove the example code and put in the function declaration. But I feel more comfortable to have the basic concepts together with an example snippet upfront when the user enters the class documentation.

wdyt? The current version of the API is here: http://tinyurl.com/buuqray

Thanks Christos On Mar 8, 2013, at 3:12 PM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: > How about a SIMPLE example at the beginning + details for each function ? > > -M > > On Fri, Mar 8, 2013 at 1:44 PM, Jay Balunas <jbalunas(a)redhat.com&gt; wrote: >> >> On Mar 8, 2013, at 3:55 AM, Matthias Wessendorf wrote: >> >>> 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 ? >> >> Yeah I agree, this is where #4 is nice because the links can take you quickly to the definitions that can then had the code. The trick would be where to put example code that is more complex or mixes function calls. >> >>> >>> Hrm... >>> >>> On Fri, Mar 8, 2013 at 8:59 AM, Christos Vasilakis <cvasilak(a)gmail.com&gt; 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(a)qmx.me&gt; 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(a)apache.org&gt; 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(a)gmail.com&gt; 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(a)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(a)lists.jboss.org >>>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>>> >>>>> -- qmx >>>>> >>>>> >>>>> _______________________________________________ >>>>> aerogear-dev mailing list >>>>> aerogear-dev(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >>>> >>>> >>>> _______________________________________________ >>>> aerogear-dev mailing list >>>> aerogear-dev(a)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(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/aerogear-dev >> >> >> _______________________________________________ >> aerogear-dev mailing list >> aerogear-dev(a)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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev

For now, we can keep it that way, but once we add more features to the classes (e.g. AGPipe), we should revisit that, I guess...