1. #1
    Ext User
    Join Date
    Apr 2007
    Posts
    51
    Vote Rating
    0
    FlexIDX is on a distinguished road

      0  

    Default API Docs

    API Docs


    Hello,

    I really enjoy EXTJS, however I really wish that all the API docs had an example use area like:

    http://extjs.com/deploy/dev/docs/out...tmlEditor.html

    I think that it would greatly increase attitude about the docs.

    Chris

  2. #2
    Sencha - Ext JS Dev Team Animal's Avatar
    Join Date
    Mar 2007
    Location
    Notts/Redwood City
    Posts
    30,506
    Vote Rating
    54
    Animal has a spectacular aura about Animal has a spectacular aura about Animal has a spectacular aura about

      0  

    Default


    Is there any particular class which is very mysterious which you think needs an example adding? I could add a little snippet...

  3. #3
    Ext JS Premium Member NOSLOW's Avatar
    Join Date
    Feb 2008
    Location
    Morrisville, NC
    Posts
    162
    Vote Rating
    -1
    NOSLOW is an unknown quantity at this point

      0  

    Default


    Animal, since you're asking, I had one trip me up the other day because the wording wasn't clear to me. It was the explanation for Ext.apply (http://extjs.com/deploy/dev/docs/?class=Ext).

    I had been using this handy method and it was working well. Then I had a need for it again in a different part, and for some reason after reading it through the second time, I felt I had to swap the first 2 parameters (which didn't work). Also, is the 3rd parameter required? If so, why? Is the returned object the same as the first parameter? I guess some examples with before/after state of the first param object and returned object would helpful.

    Now that I've taken the time to ask about it, I guess I should just go experiment myself with it in Firebug. Anyhow, it's a neat little function.

  4. #4
    Ext User
    Join Date
    Apr 2007
    Posts
    51
    Vote Rating
    0
    FlexIDX is on a distinguished road

      0  

    Default


    Animal, when I first started using ExtJS I found it verry confusing and api docs frustrating, I don't anymore, but for the total NOOB having all areas have an example use would be help full. So no there is not one I have a question on, but think it would be good if the ExtJS team during their spare time add in this information.

  5. #5
    Sencha - Ext JS Dev Team Animal's Avatar
    Join Date
    Mar 2007
    Location
    Notts/Redwood City
    Posts
    30,506
    Vote Rating
    54
    Animal has a spectacular aura about Animal has a spectacular aura about Animal has a spectacular aura about

      0  

    Default


    An example piece of code on every method would be just silly though.

    Code:
    Ext.apply(destination, source);
    Adds nothing to what the document says.

  6. #6
    Ext User
    Join Date
    Nov 2007
    Posts
    11
    Vote Rating
    0
    thewebguy is on a distinguished road

      0  

    Default


    Quote Originally Posted by Animal View Post
    An example piece of code on every method would be just silly though.

    Code:
    Ext.apply(destination, source);
    Adds nothing to what the document says.

    First of all, the example omits the default parameter, which according to the spec is a required field, since it does not have the []'s. The API seems to be rather inconsistent with how it indicates which properties and arguments are optional. Some items which are optional are indicated with an '(Optional)' but other items that I've found are optional don't have this indication in the API.

    Second of all, no, that's a rather useless example. Example code usually has a description of what to expect for the result. In the case of your example, you would have something like:

    Code:
    var destination = {foo: 'fooValue'};
    var source = {foo: 'otherFooValue', bar: 'barValue};
    var defaults = {foo: 'defaultFooValue', bar: 'defaultBarValue', baz: 'defaultBazValue'};
    
    obj = Ext.apply(destination, source, defaults);
    Followed by a description of what obj and destination contain after the function is called. By using the above example, you are telling the developer whether the source's foo value overrides the destination's, and what defaults really does. The API doesn't seem to adequetely explain what the defaults parameter does.

  7. #7
    Ext JS Premium Member NOSLOW's Avatar
    Join Date
    Feb 2008
    Location
    Morrisville, NC
    Posts
    162
    Vote Rating
    -1
    NOSLOW is an unknown quantity at this point

      0  

    Default


    Actually, Animal, your example answers a few key questions for me at a glance:
    1. It tells me the third parameter is optional, although the docs says it's required (doesn't make sense when you need to combine just 2 config blocks).
    2. It tells me that I don't need to use the object it returns. I was using it like this:
    PHP Code:
    newCombinedParams Ext.apply(params1params2, {}); 
    Why does it return an object if the first parameter is passed by value? That's confusing to someone learning to use this function for the first time.

    thewebguy, I see I'm not the only one scratching my head over this.

  8. #8
    Sencha - Ext JS Dev Team Animal's Avatar
    Join Date
    Mar 2007
    Location
    Notts/Redwood City
    Posts
    30,506
    Vote Rating
    54
    Animal has a spectacular aura about Animal has a spectacular aura about Animal has a spectacular aura about

      0  

    Default


    The required/optional status is not given.

    There is no pass by value.

    It's just a simple, one-by-one loop throigh properties.. and... well, I have to say, I'm just a volunteer, and there's just not enough hours in the day for me to do my job work, see my family, private consultancy, a bit of Ext volunteer documenting adding explanations and example code for the really difficult bits (DnD docs in 2.2 will be better + new example) and document simple things, so maybe some other volunteer can do that.

  9. #9
    Ext JS Premium Member NOSLOW's Avatar
    Join Date
    Feb 2008
    Location
    Morrisville, NC
    Posts
    162
    Vote Rating
    -1
    NOSLOW is an unknown quantity at this point

      0  

    Default


    Animal, I understand. Since you had asked and I had a specific example fresh in mind, I responded. I'm not really complaining about the docs, as I think they're excellent. I'll move on.