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

[Kris Borchers]

On Oct 9, 2012, at 2:29 AM, Matthias Wessendorf <matzew at apache.org> wrote:

> Hi Kris,
> 
> overall I like the new JS doc (see [1]). Looks pretty nice! However,
> here is some feedback on the new JS API doc!
> 
> * 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…

True. I will need to think of a different way of exposing them to the other modules without making them public. That could be fine. I might have to make AeroGear more than just a namespace and have the other modules implement AeroGear rather than just extend it and put those methods on the prototype. I'll have to think on it.

> 
> 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)

Based on the previous point, I'll have to think on how to make that work. It could be useful but it's also a pretty standard thing in JS so not a big deal if we don't expose it as many app devs already add something like that to their apps.

> 
> * On the different adapters:
> Regarding their privileged functions => Do we want to expose/document
> the privileged methods? Or 'just' the public methods?
> 
True. It probably helps to have the docs inline but don't need to include them in the generated docs. I can just add @private to them and they won't be included.
> 
> 
> Fixed a little typo:
> https://github.com/aerogear/aerogear-js/commit/3ed416af824d2b398a7db8b276ca46bf66fc2603#src/pipeline/aerogear.pipeline.js

Thanks!

> 
> Added a PR for two very simple fixes on the JS lib:
> https://github.com/aerogear/aerogear-js/pull/6

Thanks, merged.
> 
> 
> 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
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev