API Documentation and API Developer Guide

edited January 2015 in Enyo 2.5
I'm currently needing some advice on where to find information about using Enyo 2.5.1.1 I'm not trying to be overly critical. I'm just dealing with frustration that the new style API is causing. Either the information is completely missing or I have no idea how to read it.

As an example lets use enyo.Model. There are configuration options. The API section for them is listed here: enyojs.com/docs/latest/index.html#/kind/enyo.Model:options.
From that page
The inheritable default configuration options. These specify the behavior of particular API features of enyo.Model.
This tells me what the options property is for but not what the options themselves are or what they do. Btw what are they? Where are they listed? What do they do?

So off I go to the Developer Guide. I find this Building Data-Driven Apps. Cool! Lets read it. Hmm, no discussion of options. There is a section "Parsing and Converting Fetched Data" and if you look (real closely or you'll miss it) you'll see an example with this in it
options: {parse: true} but nowhere under that heading, as it's talking about overloading the parse function, does it happen to mention that if you don't have that option set your brand new parse function will never get used. It's actually not mentioned anywhere in the entire API or Guides.

Well as long as I'm here lets try one of the examples. How about the section "Fetching Models from REST Endpoints".
In the following example, we create a ContactModel subkind, providing a URL to the REST endpoint for this resource, along with the primaryKey (which will be appended to the end of the url property):
enyo.kind({
        name: "ContactModel",
        kind: "enyo.Model",
        url: "http://myservice.com/users",
        primaryKey: "user_id"
    });

    var myModel = new ContactModel({user_id: 1234});
    myModel.fetch();  // Results in an XHR request to http://myservice.com/users/1234
Looks straight forward enough. Hmm, warning:
enyo.Source.execute(): no source(s) provided for ContactModel.fetch() Huh? There's nothing in that section or example about source(s). Also as far as I can tell this statement "primaryKey (which will be appended to the end of the url property)" is completely untrue. I have yet to see that actually happen automatically.

In the end I had to read through just shy of 1k lines (922 to be precise) of Model.js source code, a migration document migration-2.3-to-2.5.md and some parts of one or two other files to figure it all out. Isn't it exactly the point of having API Documentation so that I don't have to go to these lengths to understand how to use something?

That's just problems with the Documentation on enyo.Model and that's only some of them. The entire API is lacking examples. Nothing that has configuration options actually lists them or tells what they do. There are dozens more things of this nature but this post is already too long and my frustration is obviously showing.

Btw, I never did see anywhere that primaryKey would get appended to the url property for me. I wound up having to overload the getUrl method and append my own primaryKey property to my own url property to achieve this.

TLDR;

Does there exist a complete set of information (besides the source code), or even better a working set of examples for:
enyo.Model
enyo.RelationalModel
enyo.ModelController
enyo.Collection
enyo.Source

you know … basically all the new features in 2.5.x?

Comments

  • Agree with you. Sadly, I could only find what I needed by looking at source.

    WRT to primaryKey being appended to end of URL, that should work. Try adding the source as it requests and/or adding attributes: {user_id:null} to your enyo.Model.
  • @psarin Thank you for your reply. I created a source and added it to the example. The code now looks like this:
    enyo.kind({
            name: "ContactModel",
            kind: "enyo.Model",
            url: "/api/cad/users",
            primaryKey: "user_id",
            attributes: {
                user_id: null
            },
            source: 'ajax'
        });
    
        var myModel = new ContactModel({user_id: 1234});
        myModel.fetch();  
    This results in an ajax call in the console that reads:
    XHR finished loading: GET "http://localhost/api/cad/users".
    Still lacking "/1234" appended to the end of the call. I have no idea why. Any ideas would be helpful.
  • Hmm, I guess with the update they got rid of the addition of PK to service. The model source code for buildUrl looks different in 2.5 than in 2.4.

    This is how I overcame: jsfiddle.net/warpuser/s25k6nn0/1/

    @dmikeyanderson or @RoySutton , can you comment on reason for change? Just makes sense that if REST API, then it should preserve behavior that was present in 2.4.
  • First, let me say that there are a few deficiencies in the jsdoc documentation. One of them is that, although they're documented, the various options don't generate into the output for some reason. We're trying to figure out why and will get it fixed when we do.

    Second, there are a couple of samples out there for working with models and sources. One of them is the Moonstone sample app you build from the documentation page. Another is the sample I created or the 2nd edition of Enyo: Up and Running. You can find that here: https://github.com/Enyo-UpAndRunning/restaurant-app

    Third, I will see if Cole can address some of the changes but I believe the idea was to make the ajax sources as generic as possible with the understanding that users will modify them as needed. primaryKey does not appear to be appended to the request string any longer and your solution is the correct one.

    Roy
  • @RoySutton Thank you for your reply. The Moonstone sample app is Enyo 2.4.0. The jsFiddle links specifically include Enyo 2.4.0. Thank you for the link to the restaurant-app. I will read through that.
  • Hmm, I thought I had updated all of those to 2.5.1.1. I will go back through my notes but they should have been updated.
  • OK, it took a while but I finally updated all the jsFiddle samples to be 2.5.1. The documentation on the site was correct. Please let me know if I missed anything. I didn't see anything else that was still 2.4.
  • Uhmm. Am I looking at the wrong site and documentation or am I misunderstanding what you said here? The Developer Guide is still way out of date. Specifically the part I mentioned in this post about fetching models. I would like to help you and point out more inconsistencies but to be honest I stopped reading any of the online documentation over a month ago. It became impossible to tell what was accurate, what wasn't, and what you had to go to the source code to figure out anyway. Quite frankly it doesn't appear that much (if anything) on it has changed in the last month.

    I understand that this part is off topic. I don't really get why the old api and readable source code comments (which would even parse and put my own kinds in the api. that was awsome) was scrapped for ... whatever you call this now.
  • Ah! I understand what you mean. I'll get the docs rebuilt so that it correctly reflects that a source is required. When I updated the docs I did not realize that source was not optional.
  • http://enyojs.com/docs/latest/developer-guide/building-apps/managing-data/building-data-driven-apps.html has been updated to correctly state that sources are required for fetching data and the primaryKey references have been removed. If I missed anything else please let me know.

    As to why we moved to JSDoc... we want to use a tool that was actively maintained and supported in the community rather than having to continue to maintain a custom tool only used by one project. The trickiest parts (to me) seem to be with the mapping of structures, which wasn't supported by the old docs system in any case.
Sign In or Register to comment.