This thread is solely for reporting bugs in the Ext 1.1.x documentation. (currently available here)
I'll be consolidating all the unresolved reports from the old 1.0 - 1.1RC1+ threads into this thread.
I'll officially say so (in here) when i've completed this task. in the meantime, be sure to search in the old doc bugs threads for issues before making a report here.
p.s. stupid me accidentally went and deleted the original 1.1 doc bugs thread instead of a post.
thankfully there was only 1 bug reported, and i've reposted that below.
[edit]
I've completed consolidating all unresolved doc issues from Ext 1.0 - 1.1RC1 into a single list, available below.
I've also checked all of them against the current Ext 1.1 docs to ensure they're still unresolved.
Where possible, i've included a [link] pointing to the original post / a place in the docs where the problem is evident.
Some things to note
post only documentation bugs
always CTRL+F BEFORE posting
i will regularly update the list below to reflect all verified doc issues reported in this thread
you might also want to take a look at this thread before posting
Ext Documentation Team members:
please mark any resolved issues in the list below with a strikethrough using the [s][/s] tags. thanks.
[edit]
as the list has grown really long, all classes with unresolved issues will be marked in red.
main constructor in "Public Methods" section is not hyperlinked to
corresponding description in "Method Details" section - This will no longer be an issue in the 2.0 doc center and will not be fixed for 1.x
Class Ext
Old reference to Yahoo in description for method namespace [link]
"Creates namespaces but does not assume YAHOO is the root."
incorrect description for method getModifiedRecords.
"...when you load a data store, its modified records do NOT get cleared" [link]
incorrect punctuation for description of event metachange [link]
missing method startAutoRefresh [link] - Skipped - This is not a method of Store. The OP was referring to Animal's Store override which I think he mistakenly thought had been added to Ext (?)
incorrect description for event remove [link]
-- should say "Fires when a Record has been removed from the Store"
incorrect description for event update [link]
-- should say "Fires when a Record has been updated"
incorrect description [link]
-- "This is currently only support for JsonReaders." should be "This is currently only supported for JsonReaders."
method createTemplate [link]
-- incorrect description:- should be "Creates a new Ext.Template from the DOM object spec"
-- incorrect return type:- should be Ext.Template
method translatePoints -- param An should be the return object instead [link]
incorrect description for method boxWrap [link]
-- currently says "class: A base CSS class to apply to the containing wrapper element (defaults to 'x-box')"
-- should be "class: A class name for the containing wrapper element, and a class name prefix for it's related child elements. (defaults to 'x-box')"
-- docs should also give an example usage as outlined in this post.
Class Ext.EventManager
missing function fireResize [link] - (Marked private)
incorrect description for config autoCreate's default value. [link]
should be "(defaults to {tag: "input", type: 'checkbox', autocomplete: "off"})".
Class Ext.form.ComboBox
missing config store
missing config title
missing config tpl [link] - Skipped - This is not really a config. It's more like a protected property that can be overridden by subclasses.
incorrect state name abbreviations in states.js - (also changed Tennessee TE -> TN )
Originally Posted by thejoker101
Connecticut, has CN, should be CT
Hawaii, has HW, should be HI
Maine, has MA, should be ME
Massachusetts, has MS, should be MA
Rhode Island, has RH, should be RI
Vermont, has VE, should be VT
incorrect signature for event beforequery [link]
-- currently "beforequery : ( Ext.form.ComboBox combo, String query, Boolean forceAll, Boolean cancel, Object e )", should be "beforequery : ( Ext.form.ComboBox combo, Object qe )"
-- currently "Fires before all queries are processed. Return false to cancel the query or set cancel to true. The event object passed has these properties:...", should be "Fires before all queries are processed. Return false to cancel the query or set cancel to true. The query event object passed has these properties:...".
also note that the actual qe object only has four attributes, namely
combo
query
forceAll
cancel
while the docs list 5, with e:Object - The query event object being the addition erroneous attribute.
config minChars - "The docs say that it defaults to 4. In the code if mode is local and minChars is undefined it gets set to 0. Hence, docs need modifying to take this into account." [link]
Class Ext.form.DateField
method formatDate should be marked public & doc'ed? [link] - Skipped - The post by Jack that was referred to mentions these methods in the context of being able to override them if necessary to implement custom parsing. In that sense, they could be considered protected, but they are definitely not public (should never be called directly from external code).
method parseDate should be marked public & doc'ed? [link] - Skipped - Ditto.
incorrect description for config autoCreate's default value. [link]
should be "(defaults to {tag: "textarea", style:"width:300px;height:60px;", autocomplete: "off"})".
Class Ext.form.TextField
missing config vtypeText (all subclasses of TextField also suffer from the same problem) [link]
incorrect type for config maskRe [link]
-- should be RegExp, not String
Class Ext.form.TriggerField
incorrect description for config autoCreate's default value. [link]
should be "(defaults to {tag: "input", type: "text", size: "16", autocomplete: "off"})".
the following incompatible configs are marked as hidden,
but still appear in the docs (also affects all subclasses of TriggerField): [link] - Doc parse issue, should be fixed for 2.0 beta 1
grow
growMax
growMin
Class Ext.form.TwinTriggerField
missing docs - Skipped - This is an abstract base class that can be extended, not a public component to be used directly. Comments have been added to that effect, but this class will not show up in the API docs.
Class Ext.grid.CellSelectionModel
incorrect event beforerowselect [link]
-- should be beforecellselect
incorrect description for config sortable [link]
-- "Defaults to true." should instead read "Defaults to the value of the defaultSortable property."
missing config css [link]
(and possibly missing configs attr, cellId, id and value too) - See note below...
method setRenderer > parameter fn > cell metadata description
-- missing the following parameters (refer to /ext/src/widgets/grid/GridView.js lines 834-837) [link]
cellId
id
value
-- description for parameter css is incorrect:- [link]
"I assumed it meant a style like 'width:195px', but the code in GridView adds the CSS to the cell's class list, not the style." - See note below...
event headerchange - param newText should be a String, not a Number. [link]
missing method isLocked [link] - Added in 1.1, but not 2.0 since it is no longer supported
Notes regarding CM configs: The css column property is supported (and I added it), but probably NOT for the reason you think. The GridView class is fairly complex, and you cannot simply look at everything in the cell template enclosed by a {} and assume that it's a valid config placeholder. E.g., even though there is a {css} in the template, it is in the class="" part of the template, so it is a class name, not a style config (as noted above in the setRenderer function, which I have updated). You have to dig into the actual rendering code to find the line that applies a .css property from the column object directly onto the style attribute of the cell -- the template has nothing to do with it and the css template token is only overwritten by the cell renderer. Likewise, attr is not a valid column config value, but it IS a valid parameter to setRenderer (as already noted). Column id is a supported config option, and is already on the CM config list -- it is not a valid param to setRenderer however. cellId and value, while in the template, are only set internally by GridView code and are not valid config options.
minProgressWidth [link] - Skipped - This is not a general config option, only a property that is used as the minWidth within progress() and wait(). Passing it into show() directly would have no effect (minWidth should always be used).
var cp = new Ext.state.CookieProvider({
path: "/cgi-bin/",
expires: new Date(new Date().getTime()+(1000*60*60*24*30)); // should be a comma, not a semicolon
domain: "extjs.com"
}) // missing semicolon
Class Ext.SplitLayoutRegion
missing config splitTip
missing config collapsibleSplitTip
missing config useSplitTips
missing various methods (no indication of private methods, although Ext.SplitLayoutRegion description alludes to this: "Adds a splitbar and other (private) useful functionality to a {@link Ext.LayoutRegion}.")
Class Ext.TabPanel
"old reference to YUI in the introduction text: 'Creates a lightweight TabPanel component using Yahoo! UI.'" [link]
Class Ext.tree.TreeDragZone Class Ext.tree.TreeDropZone
missing docs
Class Ext.tree.TreeEditor
missing config editDelay
Class Ext.tree.TreeLoader
"children option not documented in description of the 'node definition object' at the beginning of the description of the TreeLoader class. This option allows child nodes to be preloaded via JSON either dynamically or statically." [link]
typo in description for config dataUrl [link]
- should read "The URL from which to request a Json string which specifies an array of node definition objects representing the child nodes to be loaded."
incorrect type for config loader [link]
-- should be an Ext.tree.TreeLoader, or an object with a load method with params identical to Ext.tree.TreeLoader's load method
double quotes in the note below the example should be single quotes
Note: The root of your template must be a single node. Table/row implementations may work but are not supported due to IE"s limited insertion support with tables and Opera"s faulty event bubbling.
-- the phrase "root of your template" might also be clearer if backed by an appropriate example.
-- this note should also appear in Ext.JsonView, and should also explicitly mention "select/option" implementations
i.e. "...Table/row or select/option implementations may work but..." [link]
Note: The following are documented correctly. There appears to be an issue with the documentation parser's ability to distinguish these as separate classes for some reason. We are looking into it, but no doc changes are necessary.
Class Array
missing docs (see notes on the String class below) - Skipped
Class Number
missing docs (see notes on the String class below) - Skipped
Class String
methods indexOf and remove are incorrectly listed as belonging to Class String. [link]
these methods should belong to the Array class [link] (refer to src\core\Ext.js) - Skipped
method constrain is incorrectly listed as belonging to Class String. [link]
this methd should belong to the Number class (refer to src\core\Ext.js) - Skipped
"Would it be possible to specify the return value (null, undefined, this?) when finder methods don't find the element(s) like Element.fly, Element.get, Ext.CompositeElement.query, Ext.CompositeElement.select?" [link] - Added for El.get/fly, CompEl.select/query always return a valid CompEl that may contain 0 or more elements internally, so they are already correct.
"I can't find any documentation that describes the CSS file(s) to use. There's good descriptions of the JS files to include but nothing about CSS at all." [link] - Skipped - This is not an API doc issue. Perhaps a page in the wiki manual would be more appropriate, although I'm not sure exactly what the contents would be ("use ext-all.css"?)
Class Ext.Ajax "Suggest adding the code example and other info from Jack found here to the description of this class. An explicit example like this would help tremendously in my opinion to see how to use what is likely to be a popular class." [link]
Class Ext.ContentPanel "The doco for [ContentPanel] should include information about or a reference to the IE scroll position relative bug as outlined in http://extjs.com/forum/showthread.php?t=10726" [link] - Skipped - We can't post every possible workaround to the API docs. This one is a bit too general to document effectively in the API and only affects certain cases, so it will remain in the forums.
Class Ext.data.DataReader "There is no documentation-browser-friendly documentation for the DataReader class." [link]
Originally Posted by GArrow
Ok, I just noticed the sticky-thread about documentation issues and the comment in there to the effect that this is not-documented on purpose, because no one is supposed to instantiate one of these.
Reconsider this!
This would be like having all abstract Java or .NET classes be undocumented, with developers told "Go find the source code and read it, and you'll be told this is abstract!". Surely it makes sense to have documentation telling people not to use something directly, instead of leaving them to wonder "Why isnt this documented?" and to question the quality of Ext for it. (Which was my reaction at the time.)"
"Also, just to throw this in. Is the structure of the object-data returned by readRecords() actually documented anywhere? That also might be a good thing to document in DataReader."
Class Ext.data.JsonReader "'After any data loads, the raw JSON data is available for further custom processing.'
The docs are not clear on this. This property only exists if there is valid JSON data. If there is a data store load exception, for example, the property does not exist, rather than being null or undefined. If this is the correct intention, then it should be made clear for those making use of the load exception event so that they can apply the correct programming logic." [link]
Class Ext.DomQuery "Could you add a link to the CSS3 Simple Selector chapter in DomQuery..." [link]
Class Ext.Element "I've recently run into an issue with the Ext.Element.alignTo animation config docs and Ext.Fx, both refer to animation config objects, though Ext.Element.alignTo doesn't specify which properties of the animation config object the method actually uses..." [link] - It is somewhat confusing, but the headers of both Element and Fx discuss the differences. I added a little more explanation in the Element header to try and clarify the difference, but I'm not going to add additional comments to every single Element method that can take an anim argument.
Ext.form.BasicForm/Form "I think JSON response format (http://extjs.com/learn/Manual:Forms:Result_Format) should be included in docs." [link] - Skipped - The existing explanations and example code for Ext.form.Action.Submit and Load seem to be sufficient
Class Ext.grid.Grid "I spent a couple hours figuring out that the reason DnD from a grid to a tree failed with a rather obscure error was because I needed to set the selection model for the grid..." [link] - Skipped - This seems like possibly a bug, but not something that would go into the API docs?
Class Ext.form.ComboBox ComboBox config hiddenName - "Can we have this state a word smith'ed version of "required for form.submit"?" [link]
Class Ext.MessageBox
"It would save people a lot of grief if the documentation for the alert and confirm methods would highlight that the message boxes are displayed asynchronously (they are not a direct substitute for the regular javascript alert and confirm methods) and to provide examples of how to use these in the most common scenarios (e.g. do something after an alert(), potentially cancel a form submit following a confirm())..." [link]
"it is important that the docs indicate this" -- that "there is nothing in javascript land that can replace the blocking js alert() and confirm() methods." [link]
"the docs should show how to emulate this [blocking alert / confirm] - i.e. by having Ext.Msg.alert() invoke a callback function. I can see how to do this for a simple alert - where I came unstuck was with a confirm() that needed to control whether or not a form would be submitted." [link]
"...The alert() case is pretty trivial though, just pass a function as the third argument to Ext.Msg.alert() that triggers the activity to occur after after OK is clicked." [link]
"...The simple form submission using confirm() is trivial also - as for alert but with something like the following in the 3rd arg function..." -- example posted in thread [link]
Class Ext.util.MixedCollection "The difference beween those methods is not really clear. When to use key?" [link]
Class Ext.util.Observable
sample code for method addListener is now correctly formatted, but misaligned
"In the addListener method, there is an explanation for Combining Options. The examples in this section use the el.on() shortcut method. I think there needs to be an introduction describing exactly what on() is just before the source code block that uses it to avoid confusion. Another possibility is that maybe this example is misplaced. Should it instead be in the on() method and a link to the on() shortcut method be placed in addListener?" [link]
"Perhaps a mention in the docs that if you use a logger to monitor the progress of your application you must create a null function reference to the Ext.log() function when you remove the -debug from the script call otherwise your application will break." [link] - Skipped - There's not really anywhere in the API docs where this would go. How about a FAQ entry or wiki page?
Last edited by mystix; 24 Oct 2007 at 3:29 AM.
Reason: doc update
Class Ext.form.BasicForm
Missing method: addButton
looking at the source, the addButton method belongs to Class Ext.form.Form, which extends Class Ext.form.BasicForm.
there's no addButton method in the Class Ext.form.BasicForm.
Last edited by mystix; 8 Aug 2007 at 4:11 AM.
Reason: not a bug. not added to the list.
Incorrect sortable config option description: really defaults to false, but described as "Defaults to true".
thanks for reporting this.
the value of sortable, however, shouldn't default to false though.
it should default instead to the value of the ColumnModel's defaultSortable property.
i've updated the doc bug list accordingly.
[edit]
i've moved your question to the Help forum.
here's the link
Missing and/or Incorrect Docs - Ext 1.1.x
Ext 1.1.x Documentation Bug List
)
Originally Posted by thejoker101
Reply With Quote