API Docs Comments

thomthom

Awesomeness!!!

Dan Rathbun

The ability to add comments at the bottom of each class page has been added:
Note it is only per class and not per method.

I noticed that yesterday for the first time (and thot perhaps it had always been there, and noone has ever noticed, or bothered to post.)

(1) I think it's nearly useless way down at the bottom (ie: not many people will notice.) Per Class/Module comments are OK, but if (since they are a major SECTION headed "User Notes") there aught to be a link at the top of the page along with "Introduction" and "Methods".

(2) There is no username input field. This raises the question whether the feature is really a PUBLIC comment feature (where others can also read your posts.) OR whether it's a PRIVATE per user Note feature (where I make reminder notes for only my own private use.) The title "User Notes" would suggest the latter rather than the former.

(3) I'd prefer and encourage (in addition to Class/Module comments,) collapsable per method comments (MSDN has always had these,) WITH collapsable Topic sub branches: [Corrections, Bugs(by SU ver), Exceptions, SampleCode, Tips&Tricks, Misc, WishList*]

Method Level:( Desired Changes to the method ) / Class or Module Level:( Suggestions for new methods, constants, attributes, etc.)
When a reader is interested in a specific method, why make them go way down to the bottom of the page, and pick through (what may be in the future,) a multitude of non-sorted comments. The Sketchup module page, with it's high number of methods, is likely to get 'very busy' with comments.

(4) While we're on the subject of collapsable API page features: ALL major SECTIONs should be collapsable (ie: "Introduction", "Methods", "Class/Module Comments" ..etc..)

honoluludesktop

Hi Dan, The "AC Cobra" could be better too ... good suggestions, just kidding you ...

MartinRinehart

I just posted a comment re the correct args to WebDialog.new(). Do others get it?

This could be invaluable. The "gotcha" that stabbed you in the back, I read about it instead of also getting stabbed.

Dan Rathbun

@martinrinehart said:

I just posted a comment re the correct args to WebDialog.new(). Do others get it?

I can see it. I posted a follow up (You forgot the 9th arg; and I also noted the identifier differences for two args, the 1st and 3rd, when using a Hash.) I also noted the Hash key error, Symbol vs String.

@unknownuser said:

New notes should be posted directly to the api site. That way folks visiting the docs can see them immediately and can vote on the most helpful ones.

Anyway.. I've posted 3 times, and I now have a 'feel' for how this feature works. I HATE IT!

FIELD size limit (with no warning)* NO formatting (bold, italic, uline, font color & size, etc.)* NO code blocks* Reverse posting Order* NO post Subject (Subject is poster's Name)* NO Search feature such as we have here at SCF.* NO edit, if we mis-spell or leave out a parenthesis.* NO automatic quoting* NO bulleted or numbered lists.* NO inserting images to make a point or show a bug
Why would we possibly wish to leave behind all these features we enjoy now at SCF, and switch to a 'plain-Jane' textbox slapped at the bottom of a webpage?
Google you can do better! Google you HAVE done better!

Voting, is meaningless! It's just a subjective emotional responce with no technical usefulness. (But if your a bleeding-heart Liberal, I'm sure it makes you feel all warm and cozy.)

thomthom

Yes - basic formatting to increase readability would be nice.

thomthom

What happened to the comments? Gone?

driven

thomthom

hm...
What is the URL you use for it?
Mine just get redirected to this: http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/webdialog.html
Note the /nb/ bit - I think it's some localization redirection and the comments are missing from where I get redirect - despite everything is still in English.

driven

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

thomthom

Thanks.
I just tried in Firefox to change my preferred language from Norwegian to English - and the comments re-appeared.
I don't understand why Google pages keep messing about like this....

Jim

TBD said he was working on (or at least planning) a Ruby on Rails documentation app for the API. Any word on how it's going?

Jim

As an experiment, I used the skx project wiki to fill-in all the API classes as templates. My computer counted 1042 methods in the API that would need filled in. It's a huge amount of work even with a small army of volunteers.

But there are some definite advantages to true community documentation.

Here's the index wiki page: http://code.google.com/p/skx/wiki/ClassIndex

If anyone is interest, I can add you to the project in order to allow editing - just shoot me a PM.

thomthom

Chris Fullmer

Its great Jim! I've already done the entire constructionpoint class.

thomthom

@chris fullmer said:

Its great Jim! I've already done the entire constructionpoint class.

@unknownuser said:

point1 = Geom::Point3d.new (10,0,0)

Spaces between method name and parentheses yields warnings:
(eval):894: warning: don't put space before argument parentheses

thomthom

Would be nice if the classes listed what class their inherit from.

Jim

@thomthom said:

Would be nice if the classes listed what class their inherit from.

Well fix it!

Chris Fullmer

Eaxctly!

I copied that example from the API and I didn't notice the extra space there.

Chris

thomthom

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?