API Docs Comments
-
I added Parent reference.
And condensed the steps to create the sample CPoint in the example. (I don't see the need for all the small steps that the Google API has. At least not when they are just there to create sample objects to later demonstrate the method.)
Also added a comment of the return value in the example. Something I have been missing in the Google API docs.
Agree or disagree?
-
Jim, I just noticed the label system. You had labelled the classes inherited from Drawingelement. Nice system of organising.
-
@thomthom said:
im, I just noticed the label system. You had labelled the classes inherited from Drawingelement. Nice system of organising.
Yeah, it worked out nicely. I can't say I planned it that way, though!
-
I think we can do the same for Entity, Tool, and Observers. Though observers are not inherent from an Observer class, could be nice to have them labelled like that?
-
@thomthom said:
... Though observers are not inherent from an Observer class, could be nice to have them labelled like that?
One of my peeves with the SU API. There should be a Sketchup::Observer common class, which could have been a subclass of the Ruby base class Observer.
-
Is there a name for the classes that don't really exist other than to define an interface?
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.
-
@dan rathbun said:
I called it a "protoclass" (but not sure I used the correct term.)
@unknownuser said:
(http://dictionary.reference.com/browse/proto)":2sb0s94w]proto- 
a combining form meaning “first,” “foremost,” “earliest form of,” used in the formation of compound words ... -
@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.
-
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 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
-
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.
-
Jim, I think you forgot the link or something
-
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.)
-
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.
-
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?
-
Good point Dan. I just just blindly copying from the Google APi page.
-
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 -
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?
-
@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.1The 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.
-
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.
Advertisement