+1 for 'remove' instead of 'del'

Something like this for documentation might be useful http://docs.emberjs.com/

-- 
"The measure of a man is what he does with power" - Plato
-
@abstractj
-
Volenti Nihil Difficile

On Thursday, August 16, 2012 at 9:57 AM, Matthias Wessendorf wrote:

On Thu, Aug 16, 2012 at 2:43 PM, Kris Borchers <kris@redhat.com> wrote:
Thanks for the feedback! See responses inline.

On Aug 16, 2012, at 4:33 AM, Matthias Wessendorf <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.


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




--
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf
_______________________________________________
aerogear-dev mailing list
aerogear-dev@lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev