New API doc - typos and questions

scottlininger

WOW! no replies for almost a year!

Hey Tomot,

I'm still listening.

We have been making incremental fixes now and then. I'll take this ping as a useful reminder to check the thread for things we still need to do...

thomthom

What would your preferred channel for API documentation issues be? This thread or the comment pages on the API pages?

scottlininger

@thomthom said:

What would your preferred channel for API documentation issues be? This thread or the comment pages on the API pages?

Reporting issues via the code.google.com comments tool (which you can find at the bottom of every documentation page) is better, because it warns other users right on the page.

Dan Rathbun

Yea.. but the formatting sucks!

scottlininger

@dan rathbun said:

Yea.. but the formatting sucks!

...of course if you prefer to post nicely formatted stuff to this thread, that's cool, too!

thomthom

@unknownuser said:

@dan rathbun said:

Yea.. but the formatting sucks!

...of course if you prefer to post nicely formatted stuff to this thread, that's cool, too!

And there is some other wee issues, it quickly wraps the comments into pages, after 10 pages. And it's not always obvious.

The biggest problem is if you have your browser set to prefer a language over English, then you'll be presented with an empty comment page. (I think the comments are all gone.) Every time I have to install a new system, or use another computer here in Norway, and the preferred language is set to Norwegian I cannot see any of the comments.
I have to rearrange the preferred languages to English before I get the comments because the API doc pages forcefully redirect me to a so-called localised version for my language, even though everything is still in English.
So I can imagine there's many people not aware of the comments at the bottom of the API pages.

Dan Rathbun

It would be better to have INLINE (expandable) comment block beneath each method. I know you guys can do this because you did it on the Release notes pages.

Also expandable sample code block under each method.

Basically it needs to be more like a wiki page. Jim experimented a bit with this on his code site page.

Dan Rathbun

@unknownuser said:

@dan rathbun said:

Yea.. but the formatting sucks!

...of course if you prefer to post nicely formatted stuff to this thread, that's cool, too!

HOW! ??

I don't think it takes markup... or does it?
If so. What kind? git markup? bbCode? what?

Dan Rathbun

@Scott.. on the subject of the API... see this thread:
http://groups.google.com/group/sketchupruby/browse_thread/thread/112f655ea6067034/2c575f2d2113a894#2c575f2d2113a894

Wouldn't it be better to have a DC playsound() click function appended to the the DC class?

thomthom

@dan rathbun said:

It would be better to have INLINE (expandable) comment block beneath each method. I know you guys can do this because you did it on the Release notes pages.

? Inline comment on the release notes?

Dan Rathbun

@thomthom said:

@dan rathbun said:

It would be better to have INLINE (expandable) comment block beneath each method. I know you guys can do this because you did it on the Release notes pages.

? Inline comment on the release notes?

Yes, instead of random (newest first,) ordered comments at the page bottom...

... a poster would click an add note button WITHIN each method section. The note would be wrapped in a collapsed DIV or SPAN that is INLINE with the method section.

At the bottom of each method would be a "plus" button that has a title "Read Notes (current_num)"

If the user wished to get more info on that SPECIFIC method, they can click the "+" button, and the collapsed DIV would expand.

The same could be true for Community Contributed Sample Code Snippets. Each method could have a collapsed "snippets" section, that works in the same manner.

For an example of what I'm talking about.. see the Sketchup Release Notes page.

thomthom

@dan rathbun said:

The same could be true for Community Contributed Sample Code Snippets. Each method could have a collapsed "snippets" section, that works in the same manner.

For an example of what I'm talking about.. see the Sketchup Release Notes page.

Oh, I thought you meant that the release notes had inline comments.

Dan Rathbun

Since we are on this subject of API page format and features....

The API is still lacking:

Fully qualified class names

The organization of the docs misleads readers in some cases. For instance they would think that the PickHelper and Menu classes (as two examples,) are within the UI namespace. But they are not. They are within the Sketchup namespace.
Another example is Vertex, the Docs mislead people into thinking it's Geom::Vertex, when it's really Sketchup::Vertex

Ancestors: The mixin modules are not displayed for each class.

It would help greatly if the output of .ancestors().reject{|a|a==self} was displayed for each class and module in the API.

# Class method
class Module
  def lineage()
    ancestors.reject{|a|a==self}
  end
  def self.lineage()
    ancestors.reject{|a|a==self}
  end
end

Constants

A constants section is needed for each class and module, to list any constants defined within that namespace.

Methods
It's not clear (for the API classes,) what are class methods, and what are instance methods. (I suppose we assume they are instance methods.)* The access is not specified. (Again we assume they are all public, I suppose.)

scottlininger

@dan rathbun said:

@unknownuser said:

@dan rathbun said:

Yea.. but the formatting sucks!

...of course if you prefer to post nicely formatted stuff to this thread, that's cool, too!

HOW! ??

I don't think it takes markup... or does it?
If so. What kind? git markup? bbCode? what?

The comments don't accept markup. I'm just saying that if you have a comment that needs code formatting or something, you can post to this Sketchucation thread.

Thanks for the extra feedback, guys. I've blocked out some time to catch up on the comments.

Cheers,

tomot

I don't think Scott really gets it!
The entire API has been written by someone that passed provisionally in middle school. Then went home and proudly displayed his/her proud parents, his/her proficiency in English.
We used to give a (PP} Provisional Pass to guest students, our government had invited at tax payers expense to receive an education in our country, before they return back to their country of origin. In some cases it was an insult to give our student a PP in line with the PP definition. We also gave most of our guest students a PP, we called it a Political Pass.

Picking at random:

Group.split

    The split method is used to compute the boolean split (map overlay) of the two groups representing manifold solid volumes (this ^ arg). If the specified objects (this and arg) do not represent manifold volumes, this method fails.

Sorry! but I don't know what this entire CODE statement means:

what is a boolean split ? (this should be underlined to a definition link)
what is a manifold solid? (this should be underlined to a definition link)
what does this mean "If the specified objects (this and arg)"
where is the (map overlay)?

Speaking of overlays: the API contains not one 3d image ................" a picture is worth a thousand words"
Many of the coded API examples, will give errors when entered into the Ruby console.
I think there is work major work still to be done!

Speaking of Work to be done:

There is handful of users at this forum that would probably love to make correction to the API.
The time it took for them to make comments could have been more productively used to corrected the API.
Why not give them access to the API server and allow them to make corrections directly?

cheers!

Dan Rathbun

@tomot said:

what does this mean "If the specified objects (this and arg)"

We've already noted that these terms are confusing. The keyword this is from Javascript, and means the receiver. (It's not a Ruby keyword. It just shows the writer had a brain-fart and his web programming mind spit out the wrong word.)

Whenever you see this in the API docs, you should replace it with the Ruby keyword self, which is the current instance object, (the object on the left of the 'dot', in this case a group object.) The argument (nicked named "arg") is also a group object.

.. so to paraphrase:

self_group.split( arg_group )

Dan Rathbun

As for the other 3D geometric terms, you'll just have to open another browser to wikipedia, and paste them in.

The API docs are a technical reference, not a tutorial. It might be nice to have definition links, but we'd rather the errors were corrected first.

I'm sure you can find a browser plugin that lets you highlight text, then right-click and have a wiki lookup link on the popup menu.

I'm using Chrome now, and when I hilight "manifold solid" in your post, and right-click, an option appears on the context menu that says: "Search Google for 'manifold solid'"
It's likely I can find a Chrome extension, that will search Wikipedia, also.

TIG

To clarify the issue on group1.split(group2) [translated a little] in the Group API notes... there are equally confusing notes for ComponentInstance instance1.split(instance2)[again translated a little]...

In fact a manifold ['solid'] group can 'split' with another manifold group OR a manifold component-instance - therefore the notes are plan wrong!
The 'argument' can be a group OR an instance.

The result is always three*** new groups - one is the intersected 'volume' and the other two are the remains of the group and the 'argument' [group or instance], the originals all deleted. The intersected volume is named 'Intersection', what's left of the group is named 'Difference1' and the group of what's left or the 'argument' is called 'Difference2'. If successful the method returns an array of these groups, the API says they are listed in that order: HOWEVER, in testing the array is in reverse order! i.e. [Difference2, Difference1, Intersection].
***Somewhat perversely if the group is wholly inside the 'argument' group/instance then the result is exactly the same two volumes you started with, but they are now recast as the new groups called 'Difference1' and 'Difference2', and although there is an 'Intersection' group made and returned in the array it contains no geometry at all [i.e. (group1.split(group2))[2].entities[0]==nil] - so it might have been better to return 'nil' instead of an array [just as it does if there's a non-manifold object passed] as there was NO real 'split' at all and the originals would then be left unchanged ? If a valid 'Instance' isn't made in code [i.e. not ...entities[0]] then you could undo the 'split' if you don't want to change the two originals - however, be aware that the undo will change the references to the originals, and these will no longer be valid, so you'll need to dig further back again to re-get the references if you want to reuse them ??
These newly made groups do reuse the two original objects material[s] and apply them logically to the 'Intersection' group as its faces' materials; however, if an original object had default materials to some faces and a material applied to the group/instance itself, then the equivalent new group [like 'Difference1'] will not replicate this; rather, the equivalent faces that had the default material will now have the group.material, the new group will have the default material, and any new 'additional' faces made during the split-operation have the default material too...
These new groups also ignore the two originals' layers, with all three new groups being always on Layer0 - so if the originals are layered and you want to keep this you'll need to get references to those before they are deleted and apply the layer to.
Attributes belonging to the originals are also not replicated in the 'Difference' groups...

In a very similar way an instance can 'split' using a group OR other instance, and it returns the equivalent three groups array etc...

Other 'boolean' operations for group/component-instance have equal poor explanations and return relatively complicated results...

tomot

@dan rathbun said:

self_group.split( arg_group )

Dan you raise an interesting issue:

A good technical doc still needs to have a highlighted or underlined link, if the common English language idiom, or word, used could be taken out of context with respect to a specific computer language interpretation. Your self_group.split( arg_group ) example should qualify for such a link.

Dan Rathbun

I don't understand... I am saying it's a typographical eror, and should NOT say "this" at all, it should say "self" instead.

Anyway.. the current API documentation system stinks, and we've complained about it for years. It seems to be a low priority for Google. (Otherwise they would have hired someone who is a API documentation guru to clean up the mess.)

IMHO it is an embarrassment for Google (as a company,) knowing the quality that they can produce for other API documentation (from other Google divisions.)