Enyo 2.5.1 was it ready for release? (part 1)

I apologize in advance. Most likely this will get me censured in some way but I can't take it anymore.
this.set('rant', 'on');

Was Enyo 2.5.1 actually ready for release? After about a month of continuous frustration, aggravation and outright irritation I can honestly say I don't believe it was even close. Lets start with the obvious.

A brand new API.

The old one was pretty cool. Personally I wouldn't have changed it but that's me. I can't even imagine the number of man hours it took to rewrite it all but I digress. Ever try to use the thing? #$@&%*! #$@&%*! #$@&%*!. Tons of broken links. This is from http://enyojs.com/docs/latest/index.html#/kind/enyo.Model:status
The current state(s) possessed by the model. There are limitations as to which state(s) the model may possess at any given time. By default, a model is NEW and CLEAN. Note that this is not a bindable property.
3 of the 5 links in that one paragraph alone are broken. I could fill a small book with things like this. How about the ridiculous amounts of missing information? Well it's kind of there. You have to go to the source code to see it. Ever tried to read this #$@&%*! unformatted? Check it out:

/**
* The default options for [relations]{@link enyo.RelationalModel#relations}.
* These may vary depending on the individual [kind]{@glossary kind} of relation.
*
* @typedef {Object} enyo.RelationalModel~RelationOptions
* @property {String} type=toOne - The [kind]{@glossary kind} of relation being declared.
* Can be the name of the relation type or a reference to the constructor.
* @property {String} key=null - The [attribute]{@link enyo.Model#attributes} name for the
* relation being declared.
* @property {Boolean} create=false - Whether or not the relation should automatically create
* the instance of the related kind.
* @property {Boolean} parse=false - Whether or not the relation should call the
* [parse()]{@link enyo.Model#parse} method on incoming data before
* [setting]{@link enyo.Model#set} it on the [model]{@link enyo.RelationalModel}.
...
WAT? Nice and easy on the eyes huh? At least in the old documenting system if and when I had to go to source it was readable. None of this #$@&%*! [attribute]{@link enyo.Model#attributes} in the middle of the sentence. In case your retinas detached trying to decipher that, those are some of the options for the enyo.RelationalModel. Here's the fun part: They don't show up in the API so if you want to know what they are or what they do you have to parse that #$@&%*! Mark 1 Eyeball or just give up. What is the point of an API if I have to read the source anyway to get information on how to use something?

At this point I'm sure some are saying "Wow this guy is going a little over the top" and maybe I am. However in one post I made enyo 2.5.1 release Missing functionality and best practices I was actually asked this: "can you list out some of the things we can improve in the developer guide". So I made this post: API Documentation and API Developer Guide. The basic answer (and I paraphrase here) "Ya we wrote it but the documenter is borked for some reason. When we fix it we'll put up the new stuff". Or my favorite (paraphrased again): "Hmm all those examples are for Enyo 2.4? Wow I could of swore we fixed that. Let me check my notes". Really? What the #$@&%*! do your notes have to do with it at this point? If you don't believe me you can go look. Why would I lie in a public forum about something so easily verified? The notes could say that Developers Guide has examples for Enyo 3.0. That doesn't change the fact of what is actually on the site. Oh and btw since you never got back to me on it, are there any plans to actually update the Developers Guide? Lets move on.

Comments

  • Let me first acknowledge that we do understand the issues you're facing with the documentation. We are working to address those as quickly as we can. The unfortunate (?) thing for us in that regard is that fixing bugs and adding functionality is our primary mission and the docs have to take a back seat.

    Next, I was the person who gave you the 'let me check my notes' message. All I meant by that was that I wanted to go back and see what else I may have missed as part of the migration, not that I was going to find out you were wrong, or any other such thing. I began the process of updating the tutorial to Enyo 2.5.1 the day I responded to you and you can see that most all the fiddles are done. I got called off on to other tasks (look forward to my response to your other post) and I didn't get back to it. I will try to finish that off today.

    It was disappointing for us to put the level of effort into the new documentation and have the results not be what we wanted. We do want to make things right and we all take a lot of pride in the work we do. While there are gaps in the documentation I think you'll find that a lot more is documented than was before.

    Roy
  • edited February 2015
    While you got your note book out! You also missed the in the move to 2.5 .design file! Also the format of putting comment like " /** @lends onyx.Button.prototype */ { " was not handle right by Anaylzer2 there by tossing Ares for a fit. But yet those are Ares2 wich is in limbo so...
    John
  • Ooh. Good catch. I'm not sure what we'll be doing as regards the .desgin file. Please create Jira if you can.
  • Even better, make pull requests!
  • I went ahead and created a Jira to track the .design file. Ares is a low priority item so this may not be updated anytime soon. Please feel free to correct this and submit a patch!
  • Did a pull (both enyo/onyx) for it enyo-4133
  • Thanks, I saw! I will comment on the pull request.
Sign In or Register to comment.