New API doc - typos and questions

RichMorin · 9 Dec 2009, 08:20

General

Class and method names could be turned into links
to the appropriate API page, for ease of navigation.

Sentences should begin with a capital letter and end with
a period (etc). Phrases should not.

If a modifying phrase is used at the end of a sentence,
a comma should be added for clarity:


  the name of the attribute dictionary  if successful
                            dictionary,

Specific

http://code.google.com/apis/sketchup/docs/ourdoc/animation.html


animation -> animation
ruby      -> Ruby

... to pause, only certain ...
       pause;

http://code.google.com/apis/sketchup/docs/ourdoc/appobserver.html


... a 2nd    model ...
      second

Useful for if you need ...
---
This is useful if you need ...

http://code.google.com/apis/sketchup/docs/ourdoc/array.html


The SketchUp Array class adds ...
---
SketchUp adds ...

Specifically, it contains methods ...
---
Specifically, it adds methods ...

... arrays of 3     coordinate ...
              three

... vector. it returns ...
            It

http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionaries.html


... all of the attributes dictionaries.
               attribute

http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionary.html

Although the page does not discuss this, setting a
custom attribute with a key that contains upper-case
letters does not work.

The page does not indicate how to set an attribute
(eg, '=LenX+20') to be used as an expression.

In the entry for AttributeDictionary.each, the "value"
argument is being formatted as part of the description
for the "key" argument.

Ditto for AttributeDictionary.each_pair.

Dan Rathbun · 15 Dec 2009, 02:58

On the API docs pages, in the left nav column, whenever you have made a link bold, the cursor changes to a caret instead of the hand cursor. I suspect it's the <b> and </b> tags doing this.
example from the API HTML source:

<li><a href="/apis/..../model.html"><b>Model</b></a></li>

Perhaps if the bold tags were outside the anchor tags?

<li><b><a href="/apis/..../model.html">Model</a></b></li>

If the css specifically set a tags such: a {cursor:hand} the nested bold tags should inherit their parent's cursor setting (according to the css reference.)

thomthom · 15 Dec 2009, 07:32

The bold tag should not interfere with the cursor regardless if it's inside or outside the link element. It's default cursor property is inherit. It's either some override or other quirk. Could be a browser quirk.
In FF3.5 I don't see this behaviour. What browser do you use?

Dan Rathbun · 15 Dec 2009, 09:15

@thomthom said:

In FF3.5 I don't see this behaviour. What browser do you use?

Currently still using MSIE 7

P.S.: at MSDN it indicates if the cursor is not explicitly set, the browser decides; so it may indeed be a MSIE quirk. (I have MSIE 8 and FF on the computer in another room, I'll check and see how the site looks on that machine later today.)

thomthom · 15 Dec 2009, 11:13

@dan rathbun said:

Currently still using MSIE 7

Tried with IE8 - cursor is normal.

@dan rathbun said:

so it may indeed be a MSIE quirk.

It certainly wouldn't surprise me!

thomthom · 16 Dec 2009, 08:47

@dan rathbun said:

Point3d.<
http://code.google.com/apis/sketchup/docs/ourdoc/point3d.html#%3C

@unknownuser said:

Returns:
true if the point2 is closer to the origin.

Following the example, I get he opposite result.
The Returns: should probably read,
" *true* if the point2 is **farther** from the origin; *false* if the point2 is closer to the origin (than the receiver.)

And the anchor link http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/point3d.html#%3C doesn't work for me under FF3.5. Might be due to the < character.

Dan Rathbun · 16 Dec 2009, 10:58

@thomthom said:

And the anchor link http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/point3d.html#%3C doesn't work for me under FF3.5. Might be due to the < character.

I suggest the Google webmeister change the anchor to "#lessthan" instead of "#%3C".

I would suspect that links to - and + methods may have problems with some browsers as well.

thomthom · 16 Dec 2009, 11:17

The id for the anchor is invalid.

The correct format is:
http://www.w3.org/TR/html4/types.html#type-name

@unknownuser said:

ID and NAME tokens must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"), and periods (".").

There are a number of other HTML errors as well. They use a XHTML doctype, but empty elements is not closed with />. Looks like HTML is used - despite the doctype.

The HTTP header claims characterset ISO-8859-1 while the META tag claims UTF-8

Characters isn't escaped properly, such as the < character in the method list. (line 342)

Run it through the validator and see 67 errors. http://validator.w3.org/check?uri=http%3A%2F%2Fcode.google.com%2Fintl%2Fnb%2Fapis%2Fsketchup%2Fdocs%2Fourdoc%2Fpoint3d.html&charset=%28detect+automatically%29&doctype=Inline&ss=1&group=0&user-agent=W3C_Validator%2F1.654#line-342

No wonder things isn't always working when there's so much invalid markup.

scottlininger · 16 Dec 2009, 15:10

Thanks for all the feedback, Dan! Keep 'em coming.

thomthom · 16 Dec 2009, 15:27

@unknownuser said:

Thanks for all the feedback, Dan! Keep 'em coming.

How is your to-do list compared to Santa's list?

scottlininger · 16 Dec 2009, 15:29

Santa's got nothing on me.

thomthom · 22 Dec 2009, 08:29

Edge.reversed_in?
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/edge.html#reversed_in ?

Why is the example using a begin rescue structure? Does it on occasion cause errors?

Dan Rathbun · 28 Dec 2009, 19:51

The class Sketchup::HLR is undocumented in the API.

It's an Entity subclass.
It inherits all the Entity baseclass methods, and adds 2 of it's own:

.calculate* .num_faces

If you create a HLR object at the console, and call .parent (when it has no parent) a BUG SPLAT! results. See post: http://forums.sketchucation.com/viewtopic.php?f=11&t=24740#p212101

What is this class HLR used for? (.. as there is no .add_HLR method for the Entities collection object.)

thomthom · 30 Dec 2009, 17:56

Tool.getExtents
http://code.google.com/apis/sketchup/docs/ourdoc/tool.html#getExtents

The example given isn't a good one. From my observations, clipping occurs only when you draw outside the model boundary. So returning model.bounds is pointless.

Dan Rathbun · 31 Dec 2009, 05:01

Sketchup.send_action
http://code.google.com/apis/sketchup/docs/ourdoc/sketchup.html#send_action

You can toggle the StatusBar on/off in Ruby (PC only?) via:
Sketchup.send_action(59393)

The following have no effect on my PC in SU ver 7.1.x:
Sketchup.send_action(21019) hide Status bar and VCB
Sketchup.send_action(21020) show Status bar and VCB
Sketchup.send_action(21022) hide Status bar and VCB?
..whereas the above id 59393 does work for just the StatusBar.

[ NOTE: I've moved my VCB up to the 2nd line of the Top Toolbar Container in 2nd position after the Layers toolbar, so I'd not want the VCB turned off with the StatusBar anyhow. I see them as two different things. ]

Dan Rathbun · 31 Dec 2009, 08:40

@dan rathbun said:

(An alternative... we might create tb_Name constantsunder the UI module that would be the same for both platforms.)

Here's an example, call it 'UI_tb_const.rb'

module UI

#
# Example ONLY
#

case Sketchup;;OS
when ;WIN
	#
  tb_CAM = 'Camera'.freeze
  tb_CONS = 'Construction'.freeze
  tb_DISP = 'DisplayMode'.freeze
  tb_DRAW = 'Drawing'.freeze
  tb_EDIT = 'Edit'.freeze
  tb_GETS = 'GettingStarted'.freeze
  tb_GOOG = 'Google'.freeze
  tb_LTS = 'LargeToolSet'.freeze
  tb_LAYR = 'Layers'.freeze
  tb_STD = 'Standard'.freeze
  tb_TABS = 'SceneTabs'.freeze
  tb_PRIN = 'Principle'.freeze # spelling!
  tb_SBAR = 'StatusBar'.freeze
  tb_SECT = 'Section'.freeze
  tb_SHAD = 'Shadows'.freeze
  tb_VIEW = 'StandardViews'.freeze
  tb_VCB = 'VCB'.freeze
  tb_WALK = 'Walk'.freeze
	#
when ;OSX
	#     what are the Mac Strings?
  tb_CAM = 'Camera'.freeze
  tb_CONS = 'Construction'.freeze
  tb_DISP = 'DisplayMode'.freeze
  tb_DRAW = 'Drawing'.freeze
  tb_EDIT = 'Edit'.freeze
  tb_GETS = 'GettingStarted'.freeze
  tb_GOOG = 'Google'.freeze
  tb_LTS = 'LargeToolSet'.freeze
  tb_LAYR = 'Layers'.freeze
  tb_STD = 'Standard'.freeze
  tb_TABS = 'SceneTabs'.freeze
  tb_PRIN = 'Principle'.freeze # spelling!
  tb_SBAR = 'StatusBar'.freeze
  tb_SECT = 'Section'.freeze
  tb_SHAD = 'Shadows'.freeze
  tb_VIEW = 'StandardViews'.freeze
  tb_VCB = 'VCB'.freeze
  tb_WALK = 'Walk'.freeze
	#
end # case

end # module UI extension

Dan Rathbun · 31 Dec 2009, 08:41

UI.toolbar_names
http://code.google.com/apis/sketchup/docs/ourdoc/ui.html#toolbar_names

@unknownuser said:

The toolbar_names method is used to returns the name of all the available toolbars (this differs between PC and Mac).

(1) In the above sentence "returns" should be singular.

(2) I believe punctuation marks are supposed to go at the end of the words, ie: "Mac.)" not "Mac)." ...Language majors, confirm?

(3) It would nice if we are to do cross-platform scripts, that you list the names for PC and Mac in the API.

(4) UI.toolbar_names.sort on the PC, ver 7.1 returns:

["Camera", "Construction", "DisplayMode", "Drawing", "Edit", "GettingStarted", "Google", "Principle", "Section", "Standard", "StandardViews", "VCB", "Walk"]
.
On the [Win32] Sketchup Menu: View > Toolbars(and toolbar captions):

Principle is Principal* Edit is Modification* VCB is Measurements* StandardViews is Views* Section is Sections* DisplayMode is FaceStyle* Walk is Walkthrough
These are on the [Win32] Menu: View > Toolbars but, missing from the UI toolbar methods:
LargeToolSet* Layers* SceneTabs (on View menu )* Shadows
Missing from View Menu and toolbar methods:
StatusBar
(We can toggle it on/off [with send_action on PC], so might as well add it to the toolbar methods so we can test it's visiblilty, and use set_toolbar_visible for cross platform [if it can be toggled on MAC.])* If a user has the StatusBar off, a tool might want to instead display a messagebox if it must inform the user of some fact, so it needs to test whether it's on/off.

(5) This same Toolbar Name Identifier Set is used with the following methods, and have the same problems, missing Identifiers, etc.

UI.set_toolbar_visible* UI.toolbar_visible?

So.. we don't mind variation in the toolbar names/symbols, so long as we know what that variation is.

(An alternative... we might create tb_Name constants under the UI module that would be the same for both platforms.)

thomthom · 1 Jan 2010, 15:39

Entities.add_curve
http://code.google.com/apis/sketchup/docs/ourdoc/entities.html#add_curve

@unknownuser said:

Returns:
curve a Curve object if successful

SU7.1M1 PC returns an array of edges. Other versions untested. I'm submitting this as a bug.

thomthom · 1 Jan 2010, 15:42

Curve.move_vertices
http://code.google.com/apis/sketchup/docs/ourdoc/curve.html#move_vertices

@unknownuser said:

The vertices method retrieves a collection of all vertices in a curve.

Seem to have copied the text from Curve.vertices.
Description needs updating along with an example.

TIG · 1 Jan 2010, 18:26

@thomthom said:

Entities.add_curve
http://code.google.com/apis/sketchup/docs/ourdoc/entities.html#add_curve

@unknownuser said:

Returns:
curve a Curve object if successful

SU7.1M1 PC returns an array of edges. Other versions untested. I'm submitting this as a bug.

It's always returned an array of edges - the curve is then array[0].curve