Re: [aerogear-dev] [AeroGear.js] Persistence API - draft 0.1

On Thu, Aug 16, 2012 at 2:43 PM, Kris Borchers <kris(a)redhat.com (mailto:kris@redhat.com)> wrote: > Thanks for the feedback! See responses inline. > > On Aug 16, 2012, at 4:33 AM, Matthias Wessendorf <matzew(a)apache.org (mailto:matzew@apache.org)> wrote: > > Hi, > > looking at [1] and also reading the client JS code from the TODO app > (->app.js), I am wondering if there is a newer version of the draft? > > > This is more up to date but also needs some updating. > https://github.com/aerogear/aerogear-js/blob/master/src/pipeline/README.md > Ah... good to have some well hidden documents :-P > > > Also, inside of the rest adapter of aerogear.js the 'delete' function > is called 'del' ([2]), not sure if that's a good idea.. > > > I was using delete but that is a reserved word in JavaScript so linters hate > it. I decided to change to del but we can change it to remove or something > else. I am open to suggestions. > I know :-) but 'del' is a bit _awful_, IMO. why not remove, for now? > > > While reading the app.js file, I also noticed that some of the 'setup' > syntax needs to be documented (e.g. the draft is missing details on > settings,url etc of the cfg object): > var todo = aerogear.pipeline([ > { > name: "tasks", > settings: { > url: "/todo-server/task" > } > }, > ... > > Also - perhaps for now it is OK, but I think it (still) reads a bit > too much jQuery/ajax like?! > projectGet = Projects.read({ > ajax: { > success: function( data, textStatus, jqXHR ) { > $( "#project-loader" ).hide(); > updateProjectList( data ); > } > } > }); > (I think we had this topic already in the past, not too strong > feelings about this... but just wanted to mention this) > > > The reason there isn't documentation and that it looks like jQuery.ajax is > because it is. :) The ajax settings are basically a straight passthrough to > jQuery ajax so that any of those settings can be overridden. We can discuss > changing this but I figured why hide the fact that we're using jQuery.ajax > or add another layer of complexity over the already large list of settings > that can be changed on jQuery.ajax > fair enough, but I think with different _transport_ (read websocket or OData), we will see room for improvement. But not that of a big deal, right now; > > Oh, one last question, is there a decent/easy way to generate API docs > out of the JavaScript API? > > > I have not found one that I like. Most solutions require adding a bunch of > garbage to the source which I am not a fan of because it makes the source > itself harder to read. That being said, I am also not a fan of maintaining > that documentation by hand so hoping I can find some middle ground. Again, > open to suggestions. > Yeah, but we need for all the clients (e.g. Android, iOS and JS) some way to generate api docs. In previous jobs I've used this: http://code.google.com/p/jsdoc-toolkit/ we can evaluate a certain tool at a later point, just wanted to ensure we actually do something there :-) > > > Thanks! > > [1] https://gist.github.com/3084134 > [2] > https://github.com/aerogear/aerogear-js/blob/master/src/pipeline/adapters... > > -- > 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 (mailto:aerogear-dev@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 (mailto:aerogear-dev@lists.jboss.org) https://lists.jboss.org/mailman/listinfo/aerogear-dev