PDA

View Full Version : [Closed] Missing and/or incorrect API Docs (1.0-1.0.1)



jbowman
15 Apr 2007, 11:48 AM
getSortState
public function getSortState()
Returns the sort state of the Store as an object with two properties:


field {String} The name of the field by which the Records are sorted
dir {String} The sotr order, "ASC" or "DESC"

Parameters:

* None.

Returns:

* void

This method is defined by Store.


should be



getSortState
public function getSortState()
Returns the sort state of the Store as an object with two properties:


field {String} The name of the field by which the Records are sorted
direction {String} The sort order, "ASC" or "DESC"

Parameters:

* None.

Returns:

* void

This method is defined by Store.

brian.moeskau
15 Apr 2007, 10:33 PM
Fixed in SVN. Thanks!

KimH
16 Apr 2007, 3:58 AM
The "This would consume an XML file like this: (http://extjs.com/deploy/ext/docs/output/Ext.data.XmlReader.html)" has a <pre>...</pre> with the XML inside. But the XML is non escaped.

Animal
16 Apr 2007, 4:07 AM
Fixed in SVN.

efege
16 Apr 2007, 10:09 AM
Here is a list of occurrences of it's which should be replaced by its (http://www.englishplus.com/grammar/00000227.htm):

BasicForm.js
* does NOT remove it's markup

Combo.js
* Select an item in the dropdown list by it's data value
* Select an item in the dropdown list by it's numeric index

Component.js
* render it to it's container element

DropZone.js
* but not over any of it's registered drop nodes.
* but not on any of it's registered drop nodes.

Fx.js
* and then collapses on it's center

Menu.js
* relative to it's element of origin

StatusProxy.js
* Force the Layer to sync it's shadow and shim positions
* Causes the proxy to return to it's position of origin

TextField.js
* grow and shrink to it's content


And here we have double quotes instead of apostrophes:

DateField.js
* if it"s blank and textfield didn"t flag it

NumberField.js
* if it"s blank and textfield didn"t flag it

jay@moduscreate.com
16 Apr 2007, 10:31 AM
EventObject example:
"fu<>nction"

efege
16 Apr 2007, 11:01 AM
More.

Element.js
* @ return => @return (3 times)
* retreive => retrieve (2 times)
* prevent's => prevents

Animal
17 Apr 2007, 12:15 AM
Bravo efege! Another techie who knows the correct usage of "it's" (Apostrophe standing in for a missing "i"), and "its" (Just another possesive pronoun like "his" and "hers")

We'll be using "you're" and "your" correctly next!

efege
17 Apr 2007, 3:53 AM
Thanks Animal. And don't forget seperate. ;)

In fact, I'm always surprised that programmers systematically make those mistakes (it's, seperate, you're), since they are people who necessarily pay high attention to language details. These errors are a source of distraction while reading, and IMO that's a good reason to try to avoid them.

Well, today I found 3 real typos:

Fx.js
* provde => provide
* that will server => that will serve

TextMetrics.js
* nased => based

rtannert2
17 Apr 2007, 7:10 AM
And four cases of "its" that should be "it's":

Date.js, line 36: Whether its a leap year
Tree.js, line 361: its a move, make sure we move it cleanly
UpdateManager.js, line 237: ... it assumes its a file upload.
UpdateManager.js, 482: This is called when the transaction is completed and its time to update the element

I was pleasantly surprised to find only eleven misuses of "it's" and only four of "its" in all of the inline documentation. Great job, guys!

Rob

soad
17 Apr 2007, 7:38 AM
A good article on 5 common grammatical mistakes (http://www.copyblogger.com/5-common-mistakes-that-make-you-look-dumb/).

mystix
17 Apr 2007, 8:25 AM
I think an "English Grammar" community forum is in order :D

Then, once the internationalisation files are finalised, we can start various grammar forums for all our non-English speaking Ext users :))

brian.moeskau
17 Apr 2007, 9:24 AM
I was pleasantly surprised to find only eleven misuses of "it's" and only four of "its" in all of the inline documentation. Great job, guys!

Rob

Thanks Rob, I was hoping someone would notice this. Not that I don't appreciate the help spotting these things (I do) but no one counted the occurrences of proper usage (54 or so). When you are plowing through large quantities of documentation as quickly as we do sometimes, it's easy sometimes to make mistakes. It doesn't mean that you don't the rules of grammar.


"In fact, I'm always surprised that programmers systematically make those mistakes"


Another techie who knows the correct usage of "it's"

I don't know who you folks work with, but the vast majority of programmers with whom I have worked cannot write themselves out of a paper bag. Writing documentation and writing code are two very different things -- that's why there is a profession called Technical Writer. The skillsets are largely unrelated, other than that they both involve a lot of typing.

Oh yeah, everything mentioned is fixed in SVN. Thanks for letting us know.

efege
17 Apr 2007, 11:28 AM
Brian, my previous comment was a rather general one, showing my (probably naive) assumption that extreme care with the use of programming languages should be related to a similar care in the use of other languages too... But as you say, it does not work that way.

Please note that I wasn't referring to Ext's developers, but rather to those forum comments or blog posts spread all over the Web.

And that general comment has nothing to do with my opinion of the people who produced Ext! Your work is of great quality, as many many people keep saying every day. Too many good things were done in a short time, and I can only admire that.

jack.slocum
17 Apr 2007, 1:14 PM
Personally, I have terrible grammar and can barely compose a coherent sentence. Writing is definitely not one of my strengths!

tryanDLS
17 Apr 2007, 1:23 PM
Those 2 sentences were coherent! ;)

CurtisDuhn
24 Apr 2007, 5:02 PM
The documentation for ArrayReader includes this sample:



var RecordDef = Ext.data.Record.create([
{name: 'name', mapping: 1},
{name: 'occupation', mapping: 2},
]);
var myReader = new Ext.data.ArrayReader({
id: 0 // The subscript within row Array that provides an ID for the Record (optional)
}, myRecordDefinition);


The "var RecordDef" should be "var myRecordDefinition".

acheven
25 Apr 2007, 5:32 PM
TreeNode, TreePanel textchange event seems to be is incorrectly documented.

EDIT (tryanDLS) fixed in SVN - there were a bunch that were documented, but mistagged, confusing the doc gen.

Animal
26 Apr 2007, 12:20 AM
Fixed in SVN.

tbarstow
26 Apr 2007, 6:27 AM
I hope this isn't a duplicate, I tried searching and didn't find anything.

I thought it might be useful for the extjs team to have a single thread about missing API docs. It's super easy to miss a @class here and there, but it's not always easy to find all of your mistakes when you're the one writing the software.

Here are the ones I've noticed, I thought other people could post theirs as well:

Ext.data.HttpProxy
Ext.data.ScriptTagProxy
Ext.data.DataProxy
Ext.data.MemoryProxy
Ext.data.Record

tbarstow
26 Apr 2007, 7:39 AM
String

Animal
26 Apr 2007, 10:49 AM
The Ext.data ones are fixed, and waiting for the next generation and deployment.

String?

Well, perhaps the Ext documentation tree could include the builtin objects?

Jack, how would that work? A special directory into which we place String.js, RepExp.js, Function.js etc, with dummy, empty function defs, and standard API comments? Could this be done?

One-stop documentation.

tbarstow
26 Apr 2007, 10:53 AM
Thanks Animal, but I wasn't looking for one-stop documentation - I wouldn't expect you guys to do that!

When I wrote String I meant a place for API docs for the methods that Ext adds to String (e.g.: String.format). This has been done, for example, for the methods added to Date and Function.

BernardChhun
27 Apr 2007, 6:45 AM
The TreeEditor widget is missing from the API guys :)

ext-all-debug.js : line 17917

thanks for making all those changes/fixes

mystix
29 Apr 2007, 11:48 PM
[Ext.MessageBox]
public function updateText(String text)should be
public function updateText([String text])


and
Replaces the message box element's innerHTML with the specified string (defaults to the XHTML-compliant non-breaking space character )should be
(optional) Replaces the message box element's innerHTML with the specified string (defaults to the XHTML-compliant non-breaking space character & #160;) (i have no idea how to make &amp;#160; display correctly in a <pre> block :-? )

brian.moeskau
30 Apr 2007, 11:25 PM
I made the MessageBox.updateText param optional (checked into SVN). I changed the space char to &amp;#160; in the docs, so let's see how that renders next time Jack runs it ;)

brian.moeskau
30 Apr 2007, 11:52 PM
The TreeEditor widget is missing from the API guys :)

Docs have been added in SVN.

Animal
1 May 2007, 12:05 AM
There are a few "coding" mistakes in the ones I did in Ext.data. I can't run the generator to see the results of adding the doc comments, so I can't tell whether they'll look good or not.

I'll go through them and correct them.

brian.moeskau
1 May 2007, 12:19 AM
When I wrote String I meant a place for API docs for the methods that Ext adds to String (e.g.: String.format). This has been done, for example, for the methods added to Date and Function.

Added docs for String.format() and String.leftPad() in SVN. Also added the String header block so that it should show up in the docs now.

var1en
1 May 2007, 5:55 AM
http://extjs.com/deploy/ext/docs/output/Ext.grid.Grid.html#configs

Error with options.

brian.moeskau
1 May 2007, 6:08 AM
Animal has already checked in fixes for all the Grid doc errors to SVN. There were some syntax issues that were causing the parser problems.

mystix
1 May 2007, 6:17 AM
hi brian, in view of the parser problems, do we still carry on reporting missing / incorrect API docs? or do we leave them off till the 15th of may?

brian.moeskau
1 May 2007, 6:41 AM
Let me clarify -- the parsing problems are not issues with the parser itself, but issues with how a few sections of comments were written. Because the parser is not yet nicely packaged for anyone aside from Jack to use, other people cannot check their work. So sometimes docs contributed by people other than Jack end up with syntax errors that don't get caught until after Jack updates everything.

So yes, any additional issues should be reported. What happens on May 15th?

Animal
1 May 2007, 6:41 AM
I don't know if the parser really does have problems. I had just done some of the comments wrong.

mystix
1 May 2007, 6:57 AM
Let me clarify -- the parsing problems are not issues with the parser itself, but issues with how a few sections of comments were written. Because the parser is not yet nicely packaged for anyone aside from Jack to use, other people cannot check their work. So sometimes docs contributed by people other than Jack end up with syntax errors that don't get caught until after Jack updates everything.

So yes, any additional issues should be reported.ok, will do. found some undocumented stuff to report. for starters, Ext.Element's getViewSize() method:
getViewSize : function(){
var d = this.dom, doc = document, aw = 0, ah = 0;
if(d == doc || d == doc.body){
return {width : D.getViewWidth(), height: D.getViewHeight()};
}else{
return {
width : d.clientWidth,
height: d.clientHeight
};
}
},



What happens on May 15th?jack's global announcement for 1.0.1 says "04-30-2007 until 05-15-2007", so i'm guessin Ext 1.1? ;)

tryanDLS
1 May 2007, 7:31 AM
jack's global announcement for 1.0.1 says "04-30-2007 until 05-15-2007", so i'm guessin Ext 1.1? ;)
I wouldn't take any special meaning from the expiration date of the announcements. For now, that' just so they automatically unsticky themselves. If nothing new is released, the expiration date just gets bumped.

mystix
1 May 2007, 8:16 AM
I wouldn't take any special meaning from the expiration date of the announcements. For now, that' just so they automatically unsticky themselves. If nothing new is released, the expiration date just gets bumped.

my bad. :">

n01champion
1 May 2007, 10:29 AM
getSelectedCell function is not documented

It's part of the cellSelectionModel

mystix
1 May 2007, 11:42 PM
[Ext.form.TextField > Config Details]
msgTarget Value-Description table display is messed up.

[Ext.form.Field > Config Options]
missing fieldLabel config option.

SteveEisner
8 May 2007, 11:09 AM
FYI
MessageBox.confirm says that it only passes 1 argument to the callback function, but it actually passes 2: the btn ID and some sort of value (activeTextEl.value? not sure what it is)

This messed us up when we passed in a createDelegate that appended params, and all the params were shifted ...

jay@moduscreate.com
9 May 2007, 6:35 AM
Badly formatted: http://extjs.com/deploy/ext/docs/output/Ext.form.ComboBox.html#config-msgTarget

CurtisDuhn
9 May 2007, 2:37 PM
It's not mentioned in the docs, but it appears that you can set the dataIndex config option if you need to load a form field with a record attribute named differently from your field name or ID.

mdelanno
10 May 2007, 12:18 AM
The el argument is missing.

public function LoadMask(Object config) -> public function LoadMask(String/HTMLElement/Ext.Element el, Object config)

And in Ext.data.Connection.request

resopnse -> response

tryanDLS
10 May 2007, 2:23 PM
The el argument is missing.

public function LoadMask(Object config) -> public function LoadMask(String/HTMLElement/Ext.Element el, Object config)

And in Ext.data.Connection.request

resopnse -> response
Both fixed in SVN

mystix
15 May 2007, 1:08 AM
[Ext.form.DateField]

Public Events > blur (incomplete description)
blur : (Ext.form.Field this)
Fires when

[edit]
missing: formatDate and parseDate methods

Jul
16 May 2007, 3:25 PM
There is a minor error in the trackMouseOver default param in Grid.js starting at line 304 (from rev 348 in SVN):

Currently reads:

/**
* @cfg {Boolean} trackMouseOver True to highlight rows when the mouse is over. Default is false.
*/
trackMouseOver : true,

Should be:

/**
* @cfg {Boolean} trackMouseOver True to highlight rows when the mouse is over. Default is true.
*/
trackMouseOver : true,

tryanDLS
22 May 2007, 9:59 AM
There is a minor error in the trackMouseOver default param in Grid.js starting at line 304 (from rev 348 in SVN):

Currently reads:

/**
* @cfg {Boolean} trackMouseOver True to highlight rows when the mouse is over. Default is false.
*/
trackMouseOver : true,

Should be:

/**
* @cfg {Boolean} trackMouseOver True to highlight rows when the mouse is over. Default is true.
*/
trackMouseOver : true,

Fixed in SVN and added the default values for some others.

tryanDLS
22 May 2007, 10:03 AM
[Ext.form.DateField]

Public Events > blur (incomplete description)
blur : (Ext.form.Field this)
Fires when

[edit]
missing: formatDate and parseDate methods
blur is fixed in SVN. formatDate and parseDate are currently marked private.
EDIT: Just a saw another thread where Jack recommended the use of the these 2 functions, so I guess they should get changed to public :)

mystix
24 May 2007, 12:50 AM
EDIT: Just a saw another thread where Jack recommended the use of the these 2 functions, so I guess they should get changed to public :)

hehe... thanks :D

mystix
24 May 2007, 2:10 AM
[Ext 1.0.1a]

in the events for Ext.grid.CellSelectionModel,

beforerowselect : (SelectionModel this, Number rowIndex, Number colIndex)
Fires before a cell is selected.should be
beforecellselect : (SelectionModel this, Number rowIndex, Number colIndex)
Fires before a cell is selected.

tryanDLS
24 May 2007, 9:55 AM
[Ext 1.0.1a]

in the events for Ext.grid.CellSelectionModel,

beforerowselect : (SelectionModel this, Number rowIndex, Number colIndex)
Fires before a cell is selected.should be
beforecellselect : (SelectionModel this, Number rowIndex, Number colIndex)
Fires before a cell is selected.
Looks like somebody caught this one already - fixed in SVN.

mystix
24 May 2007, 11:35 AM
Looks like somebody caught this one already - fixed in SVN.

my apologies. i searched this thread only for missing / incorrect docs. :">

si-rus
24 May 2007, 11:52 AM
getAt(String index) : Ext.data.Record
Get the Record at the specified index.

Most likely

getAt(Number index) : Ext.data.Record
Get the Record at the specified index.

tryanDLS
24 May 2007, 12:10 PM
getAt(String index) : Ext.data.Record
Get the Record at the specified index.

Most likely

getAt(Number index) : Ext.data.Record
Get the Record at the specified index.
Fixed in SVN

haibijon
26 May 2007, 6:13 AM
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.

There are apparently two seperate animation config objects, one for alignTo/standard Ext.Element animations, and then another animation config object for Ext.FX animations. The current docs are really ambiguous in reference to their animation config objects.

If possible, I think the actual config options should be specified as they're not all consistant (especially since Ext.Element inherits Ext.FX and both class' docs refer to a single animation config object, yet have different config properties)

Please see this thread for an example of what I mean... (http://extjs.com/forum/showthread.php?t=6812)

sjivan
28 May 2007, 12:20 PM
QuickTips
=======
In the example code QuickTip's are initialized by calling the static method Ext.QuickTips.init(). The init method is not in the generated docs. Also the init method has a comment in the code stating that it is private.

'text' and 'title' configuration properties are missing from the QuickTips config documentation.

Button config
==========
'cls' property for css styling missing

Field config
========
fieldLabel, name, width properties missing

Ext.data.Record
============
The source code has docs that are not present in the generates documentation.

rtannert2
31 May 2007, 5:53 AM
In the comment block for the load method in HttpProxy.js, the following line has ) where it should have }:


* @param {Ext.data.DataReader) reader The Reader object which converts the data

cwells
31 May 2007, 9:18 AM
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:



var grid = new Ext.grid.EditorGrid ( 'phone-grid', {
enableDrag: true,
selModel: new Ext.grid.RowSelectionModel ( { singleSelect: false } ) // error without this line
// ... other stuff
}

efege
31 May 2007, 9:43 PM
Ext.override, though mentioned several times on forums posts, is not documented on http://extjs.com/deploy/ext/docs/output/Ext.html.

brian.moeskau
31 May 2007, 10:07 PM
* @param {Ext.data.DataReader) reader The Reader object which converts the data

Fixed.

brian.moeskau
1 Jun 2007, 12:30 AM
QuickTips
=======
In the example code QuickTip's are initialized by calling the static method Ext.QuickTips.init(). The init method is not in the generated docs. Also the init method has a comment in the code stating that it is private.

'text' and 'title' configuration properties are missing from the QuickTips config documentation.

Doc'd init and added text, title, cls and width config attributes. FYI, init is not static, it's just a singleton method.


Button config
==========
'cls' property for css styling missing

Added, and made a few other minor fixes.


Field config
========
fieldLabel, name, width properties missing

Added name to Field. FieldLabel only applies to fields being added to forms, not to fields generally. Because of this, I added comments to Form.add to note this. Similarly, while width does apply to fields, it needs to be documented in one of the base classes, most likely in BoxComponent which is actually new in the last release and not yet doc'd at all (I'll get to it soon).


Ext.data.Record
============
The source code has docs that are not present in the generates documentation.

Various issues in the Ext.data namespace have already been fixed in SVN since the last release, but not yet regenerated on the public site, including this one.

brian.moeskau
1 Jun 2007, 12:49 AM
Ext.override, though mentioned several times on forums posts, is not documented on http://extjs.com/deploy/ext/docs/output/Ext.html.

Added in SVN.

KimH
1 Jun 2007, 3:28 AM
I believe the Config options are wrong here... http://extjs.com/deploy/ext/docs/output/Ext.grid.Grid.html#configs

Animal
1 Jun 2007, 3:57 AM
Those have been fixed in SVN for quite a long time.

Perhaps there should be a deployment of a freshly generated doc set so that people can start looking for missing/incorrect docs that are still missing or incorrect.

efege
1 Jun 2007, 4:04 AM
Perhaps there should be a deployment of a freshly generated doc set so that people can start looking for missing/incorrect docs that are still missing or incorrect.

If that was feasible, it would be very appreciated! I have been compiling a list of errors since about a month ago, but still haven't posted them, and I wouldn't like people wasting their time checking already fixed errors.

sjivan
2 Jun 2007, 6:54 AM
Ext.from.BasicForm
==============
config options for 'load' missing

Ext.data.Connection and Ext.data.HttpProxy
=================================
config options not documented

Ext.form.ComboBox
==============
'tpl' config param for setting Template missing

Ext.grid.Grid
=========
config options for Grid, ColumnModel doc'ed in source but not in generated docs. Not sure if this too has been fixed in SVN. 'enableColLock' config aslo missing

from Grid.js
========
/**
* @cfg {Boolean} True to highlight rows when the mouse is over. Default is false.
*/
trackMouseOver : true,

efege
4 Jun 2007, 4:34 AM
Hi, so this is Monday 4th of June, and Ext 1.1 beta 1 is publicly available for download (http://extjs.com/download). =D>

What about this thread? I assume we must forget about 1.0x docs and begin reporting just the remaining bugs on 1.1, ok? Or should the discussion about a beta release go to Prerelease Builds Discussion?

tryanDLS
4 Jun 2007, 7:32 AM
I've closed this thread. Please report 1.1 doc bugs to the new thread (http://extjs.com/forum/showthread.php?p=36533)