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

[Matthias Wessendorf]

On Thu, Aug 16, 2012 at 3:52 PM, Bruno Oliveira <bruno at abstractj.org> wrote:

>  +1 for 'remove' instead of 'del'
>
> Something like this for documentation might be useful
> http://docs.emberjs.com/
>



that uses http://code.google.com/p/jsdoc-toolkit/  as well :))


>
> --
> "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 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
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20120816/bc63bc5c/attachment-0001.html