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

[Matthias Wessendorf]

On Thu, Aug 16, 2012 at 2:43 PM, Kris Borchers <kris at redhat.com> wrote:
> Thanks for the feedback! See responses inline.
>
> On Aug 16, 2012, at 4:33 AM, Matthias Wessendorf <matzew at 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/rest.js#L74
>
> --
> 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
>
>



-- 
Matthias Wessendorf

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