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

[Matthias Wessendorf]

A few more things.

* I am missing the documentation for the arrays that store the
different adapters (e.g. stores, pipes, modules)
- For instance, the 'pipes' array is currently only mentioned in a code snippet:
http://staging.aerogear.org/docs/specs/aerogear-js/AeroGear.Pipeline.adapters.Rest.html

- The Pipeline Module itself does not talk about it (similar in the
DataManager and Auth modules)

* Is the dataTypeType in here a typo?
http://staging.aerogear.org/docs/specs/aerogear-js/AeroGear.Auth.adapters.Rest.html

* missing setting values:
Looking at:
http://staging.aerogear.org/docs/specs/aerogear-js/AeroGear.Auth.adapters.Rest.html

I think the 'agAuth' or 'tokenName' values are missing in the documentation.


NOTE: I am more than happy to file JIRAs for EACH of the above items,
but wanted to raise them here before... since I wasn't 100% sure if
things were done on intention or not!


-Matthias


On Tue, Oct 9, 2012 at 10: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...
>
>
>
>
>>
>> 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



-- 
Matthias Wessendorf

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