[aerogear-dev] [JS Doc] feedback on the new JS-Doc

[Matthias Wessendorf]

On Tue, Oct 9, 2012 at 2:32 PM, Kris Borchers <kris at redhat.com> wrote:
>
> On Oct 9, 2012, at 3:16 AM, Matthias Wessendorf <matzew at apache.org> wrote:
>
>> One more...
>>
>>> * http://staging.aerogear.org/docs/specs/aerogear-js/AeroGear.html
>>> - add/remove/ajax: These are internal helpers/utilities, right? Not
>>> sure if that should be exposed...
>>
>> wouldn't it be more logical if the add/remove were documented on the
>> different modules ?
>>
>> http://staging.aerogear.org/docs/specs/aerogear-js/AeroGear.DataManager.html
>>
>> I think users would benefit if the add/remove was mentioned on each
>> module, instead of on the 'global' AeroGear.html file.
>>
>> I think the current way maybe a bit confusing...
>>
> Maybe … I hate having to duplicate those docs across all of those files so if one changes they all have to be updated. I'll think about it with the review of the previous e-mail's points

I understand the coding behind it - but IMO it's pretty odd to have
them documented on the root.
If you just look at the DataManager.html doc file (for instance), hard
to see that you could even use add/remove.

IMO the current solution (documentation) is not ideal. I think it's confusing.

Can you show 'inherited' functions ?



>>
>>
>>
>>>
>>> I think the 'isArray' is a bit different => I can see that some
>>> END-USER finds 'AeroGear.isArray(argument)' pretty useful!
>>> (compared to something like AeroGear.ajax(...), where you already need
>>> to pass in an AeroGear object)
>>>
>>> * On the different adapters:
>>> Regarding their privileged functions => Do we want to expose/document
>>> the privileged methods? Or 'just' the public methods?
>>>
>>>
>>>
>>> Fixed a little typo:
>>> https://github.com/aerogear/aerogear-js/commit/3ed416af824d2b398a7db8b276ca46bf66fc2603#src/pipeline/aerogear.pipeline.js
>>>
>>> Added a PR for two very simple fixes on the JS lib:
>>> https://github.com/aerogear/aerogear-js/pull/6
>>>
>>>
>>> Greetings,
>>> Matthias
>>>
>>>
>>> [1] http://staging.aerogear.org/docs/specs/aerogear-js/
>>>
>>>
>>> --
>>> Matthias Wessendorf
>>>
>>> blog: http://matthiaswessendorf.wordpress.com/
>>> sessions: http://www.slideshare.net/mwessendorf
>>> twitter: http://twitter.com/mwessendorf
>>
>>
>>
>> --
>> 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
>
>
> _______________________________________________
> 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