Re: General
@richmorin said:
Class and method names could be turned into links
to the appropriate API page, for ease of navigation.
Rich, note the left Nav column. The second box labeled "Quick Reference" has exactly these Class index and Method index links.
Re: Array class Introduction
@richmorin said:
Specific
http://code.google.com/apis/sketchup/docs/ourdoc/array.html
> The SketchUp Array class adds ...
> ---
> SketchUp adds ...
>
The correct ruby term is **extends** (as in extending a base class.) The way it is currently worded, a reader might misconstrue that the class is a custom class within the Sketchup namespace (ie, Sketchup::Array ), which is NOT the case. My version would read " Sketchup extends the standard Ruby Array class with additional methods.."
@richmorin said:
(same subject... Array class Introduction)
> Specifically, it contains methods ...
> ---
> Specifically, it adds methods ...
>
The word ***add*** is better here, because it's more specific (as to the manner in which the base Array class was extended.)
Re: AttributeDictionaries.each
@richmorin said:
http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionaries.html
> ... all of the attributes dictionaries.
> attribute
>
For clarity I would suggest rewording the method description as: " *The each method is used to iterate through the entire list of attribute dictionary objects*."
@unknownuser said:
Throws an exception if there are no keys.
(1) What specific exception is thrown? KeyError or IndexError or a custom SU error class? (the API should state what it is we may need to trap with a rescue clause.)
(2) Error conditions are not documented in a uniform manner throughout the API. Sometimes they are noted in the method description paragraph; sometimes (as in this case,) as a separate paragraph of the description section; other times in the ***Returns:*** section. Perhaps it's time to add a third ***Exceptions:*** section list, where the list labels would be exception class names and the defintion text would be the reason why the exception is raised.
(3) Why does this method raise an exception, and the *.[]* method returns *nil* when there are no keys (or matches)? IMHO, the proper ruby way is to raise the correct exception in both cases, AND provide the *.empty?*, *.has_key?* and *.length* (or similar named) methods so scripts can use them in conditional statements when checking the Dictionary lists. Example:
model = Sketchup.active_model
attrdicts = model.attribute_dictionaries
if not attrdicts.empty?
attrdicts.each {|key,value| puts key.to_s+" is "+value.to_s }
else
puts "Dictionary List is Empty!"
end
It just seems strange, as these are Array or Hash type classes, and they didn't inherit some of the basic funtionality, that they should have. Which brings us to...
**(4) AttributeDictionaries.member?** is undocumented. Not that it does us any good, as it only takes an object, not a string name (returns false even for vaild dictionary names.) This means you need to know it exists in the first place, so why would we need to test it's membership? *.member?* is normally an alias for *.has_key?*, so if this method could be updated to ALSO take the dictionary string name, it would serve us well.
Re: AttributeDictionaries Introduction
@unknownuser said:
You access this class not by performing an AttributeDictionaries.new but by grabbing a handle from an existing entity.
http://code.google.com/apis/sketchup/docs/ourdoc/entity.html#attribute_dictionaries
This only works for [ruby:2bffgwcd]model[/ruby:2bffgwcd] objects (seems the model has an empty dictionary list by default.) Other entities will return nil (as they do not have an AttributeDictionaries object created until after an AttributeDictionary has been attached.); the API should note that first a script needs to create an AttributeDictionary object, before the AttributeDictionaries object can be 'grabbed' (because it does not yet exist.)
UPDATE (2010JAN23-DanRathbun) PC ver 7.1.6860:
REVISED (2010JAN28-DanRathbun) See later post (this forum):
[url=http://forums.sketchucation.com/viewtopic.php?f=180&t=17047&p=218516#p218516:2bffgwcd]http://forums.sketchucation.com/viewtopic.php?f=180&...p218516[/url:2bffgwcd]
[i:2bffgwcd]Re: AttributeDictionary Introduction[/i:2bffgwcd]
@unknownuser said:
An Entity or Model object can have any number of AttributeDictionaries.
[url:2bffgwcd]http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionary.html[/url:2bffgwcd]
This is confounding the use of the two differnet class names. (The parent should have been named [i:2bffgwcd]DictionaryList[/i:2bffgwcd], or better yet, [i:2bffgwcd]AttributeLibrary[/i:2bffgwcd]. [as in: shelf space for many dictionary volumes.]) Actually each entity can have only 1 [ruby:2bffgwcd]AttributeDictionaries[/ruby:2bffgwcd] object. The sentecnce should read "[ruby:2bffgwcd]An Entity or Model object can have any number of AttributeDictionary objects[/ruby:2bffgwcd]."
Both AttributeDictionaries and AttributeDictionary Introductions should have an 'also see note' directing readers to Entity class methods [ruby:2bffgwcd].attribute_dictionary[/ruby:2bffgwcd] and [ruby:2bffgwcd].attribute_dictionaries[/ruby:2bffgwcd] on how to create them.
It would have been nice to have a [ruby:2bffgwcd]new[/ruby:2bffgwcd] method for the child dictionary objects at least. We could then call something like:
myEntity = Sketchup.active_model.selection[0]
#
# this is more intuitive
attrdict = AttributeDictionary.new("My Dictionary", myEntity)
#
# this is not so
attrdict = myEntity.attribute_dictionary("My Dictionary", true)
