API Docs Comments

[Dan Rathbun]

@jim said:

For example, there is no actual Tool base class in Sketchup. It's just a convention. An instance of any object can be a "Tool" if it responds_to certain instance_methods.

Reference, a topic at GoogleGroups:

@unknownuser said:

(http://groups.google.com/group/sketchupruby/tree/browse_frm/thread/6e6ead6cade3807a/440e3c753370ab23?rnum )":c5ik998j]
@unknownuser said:

(http://groups.google.com/group/sketchupruby/tree/browse_frm/thread/6e6ead6cade3807a/f1c8fdd8b6d98c72?rnum )":c5ik998j]2. I am sort of puzzed about what makes a tool. Is it the fact that it uses "Tool" methods?

Yes it is strange. There is not a Sketchup::Tool protoclass actually defined (but there could be, and might be argued, should be.)

So actually what makes a tool is that Sketchup treats an object as a tool if you call Sketchup.select_tool( object ); as up to that point Ruby and Skecthup would not know what it is supposed to be.

So then, SU assumes that it 'could' have any of the standard tool callback methods. I think .activate would be considered as a required method. While the tool is active, Sketchup sends information to the object by calling the method names defined in the API.

I called it a "protoclass" (but not sure I used the correct term.) IF there was a Sketchup::Tool class (and there really should be to be 'proper' OOP Ruby,) then it would called the superclass of the custom Tool subclass(es) that we write.

It would NOT be a baseclass, because they are defined at the toplevel, and generic to the entire Ruby world, not just Sketchup.

[Dan Rathbun]

So...

@jim said:

Is there a name for the classes that don't really exist other than to define an interface?

Would they then be called protoless classes ??

[Dan Rathbun]

@dan rathbun said:

So...

@jim said:

Is there a name for the classes that don't really exist other than to define an interface?

Would they then be called protoless classes ??

Looking through Dictionary.com (Thesaurus tab) for 'protoless' synonyms:

• Concocted
• Contrived
• Ad lib

Or perhaps:

• demiclass

[Jim]

This is an html page of the SketchUp API classes. Save it as a .html file, and then bookmark it in Firefox. Edit the bookmark to open in the Sidebar. Instant API sidebar.

[Chris Fullmer]

Jim, I think you forgot the link or something

[Jim]

Hmmm, first time that's ever happened...

The forum doesn't like HTML, so I uploaded it encoded.

• Open it in Notepad++,
• Select all
• Plugins > MIME Tools > Base64 decode
• Save as api_sidebar.html

(same way to decode those non-rbs encrypted scripts, btw.)

---

api_sidebar.txt

[Dan Rathbun]

ISSUE: the improper use of "Parent"

Speaking specifically on: ConstructionPoint

Familial terms: ie: parent and child are reserved for the instance object heirarchy, such the HTML Document Object Model, and in our case the Sketchup SKP document heirarchy.

Example: the model object has children that can be Component, which can have children Groups, which may have children Edges and Faces, and so on.
A Face instance inside a Group has THAT Group instance as it's Parent, but Group is NOT the superclass of Face.

You will notice that in the SU API all .parent methods refer to the specific instance object's relationship within the document heirarchy.

The correct terms are superclass, subclass, and class; all always LOWERCASE because Class (UPPERCASE,) is a specific class Identifier.

[Jim]

Thanks Dan,

The ConstructionPoint page looks good.

I am all for using the right terminology - i just don't know what that is all the time.

How about ancestors and descendants?

[thomthom]

Good point Dan. I just just blindly copying from the Google APi page.

[thomthom]

Btw, is the data on these pages possible to extract in some manner?
I have been wanting to make a script that analyses the methods used in a given set of .rb files and check compatibility with SU6, 7.0 or 7.1

[thomthom]

hmm.. yea ... the SU version when the methods are introduced from this documentation. Do we add it to the header? Under the list of ancestors?

[Jim]

@thomthom said:

Btw, is the data on these pages possible to extract in some manner?
I have been wanting to make a script that analyses the methods used in a given set of .rb files and check compatibility with SU6, 7.0 or 7.1

The wiki is a mercurial repository. It can be cloned:

$ hg clone https://wiki.skx.googlecode.com/hg/ skx-wiki

So the pages can be sync'd locally and processed using scripts, and pushed back to the online repository. I am doing this to generate sidebar pages to contain a list of methods plus inherited methods.

As an example of a utility file, there is a page named MasterList.wiki I use to generate the Class Index .

Some kind of automated build is going to be needed sooner or later. This might mean that there needs to be a lot of extra source files in the repository (OK because only .wiki files show up as pages online.) Each page may have a file for a header section, a method section, and a footer section. Or maybe even each method is stored in its own file. Then the build script puts everything together into a .wiki page.

The build scripts could be a sub-folder in the repository, so they could be collaborated on also.

Then a dependency-based build programs such as Rake would be used to build and update only pages which have been edited.

I would like to somehow keep it all editable online, too. But then it gets complicated because we don't edit the actual wiki pages, but wiki pages that would be used as the source for the real pages.

[Jim]

As if documenting the entire API wasn't crazy enough, here's crazy idea #2 - create a mock-up Ruby library of the entire SketchUp API (called Mock-Up, naturally.)

Document the source code classes, methods, constants, etc as if it were actual code (because it is.)

Generate docs from source code.

With the potential added benefit of being able to test SketchUp plug-ins outside of Sketchup.