API Docs Comments

remus · 10 Mar 2010, 20:26

The ability to add comments at the bottom of each class page has been added: http://code.google.com/apis/sketchup/docs/classes.html

Note it is only per class and not per method.

cheers google people

thomthom · 10 Mar 2010, 21:33

Awesomeness!!!

Dan Rathbun · 11 Mar 2010, 02:33

@remus said:

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 · 11 Mar 2010, 19:22

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

MartinRinehart · 12 Mar 2010, 19:19

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 · 13 Mar 2010, 00:40

@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 · 15 Mar 2010, 17:00

Yes - basic formatting to increase readability would be nice.

thomthom · 22 Mar 2010, 08:55

What happened to the comments? Gone?

driven · 22 Mar 2010, 09:05

thomthom · 22 Mar 2010, 09:14

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 · 22 Mar 2010, 09:30

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

thomthom · 22 Mar 2010, 09:43

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 · 20 May 2010, 15:27

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 · 23 May 2010, 23:04

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.