Detailed feedback thread: 6-gadgets_JS.html

[Dan Peterson]

As per the note below, please use this thread to discuss potential improvements to the gadgets JS Doc:
http://opensocial-and-gadgets-spec.googlegroups.com/web/6-gadgets_JS.html

Thanks,
-Dan

---------- Forwarded message ----------
From: Dan Peterson <dpet...@google.com>
Date: Fri, May 9, 2008 at 6:27 PM
Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related spec updates
To: opensocial-and-gadgets-spec <opensocial-an...@googlegroups.com>


Hi folks,

As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.

You can find all 6 of these documents uploaded into the "Files" section of this Google Group: http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name

The draft documents published are (please note that some of the links in the files might not work as this is only a staged copy):

• 1 - OpenSocial 0.8 Release Notes
• 2 - OpenSocial 0.8 Specification
• 3 - OpenSocial 0.8 RESTful API Specification
• 4 - gadgets Specification
• Canonical gadgets XSD
• Extended gadgets XSD
• gadgets Message Bundle XSD
  
• 5 - opensocial.* 0.8 JS doc
• 6 - gadgets.* JS doc

I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.

Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.

You can learn more about the event at: http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
(RSVP is here: http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )

Looking forward to your feedback (in the appropriate thread ;),
-Dan

[Kevin Brown]

The first paragraph in this document says "must...", which contradicts the XML spec which says that you can use either <Require> or <Optional>.

The note about igoogle doesn't belong here. This is a specification, not a developer's guide.

There is no explanation for what "Core API" and "feature specific API" means. What makes "Prefs" core? Based on the first paragraph, it sounds like to use the "Prefs" feature I have to add this line to my gadget:

<Require feature="Prefs"/>

And yet, clearly, that isn't the case on any implementation. It causes a rendering error on most sites. Are all implementations wrong?

To be clear, the spec currently says that if I want to include every API on this list, the syntax is:

<Require feature="Prefs"/>
<Require feature="io"/>
<Require feature="json"/>
<Require feature="util"/>
<Require feature="MiniMessage"/>
<Require feature="Tab"/>
<Require feature="TabSet"/>
<Require feature="flash"/>
<Require feature="pubsub"/>
<Require feature="rpc"/>
<Require feature="views"/>
<Require feature="skins"/>
<Require feature="window"/>

I'm being intentionally difficult here. The spec has to be correct, it can't just assume that implementations will "know" how this stuff works.

The return types on most of these methods are "Boolean", "String", and "Array.<Something>". Array.<Something>, but right now no containers return these types -- they all return "boolean" "string" and arrays of items. These are distinct entities in javascript. Boolean is not the same thing as boolean (as in the values "true" and "false". What does Array.<Something> mean? JSDoc mentions this, but it's not a standard part of javascript, so there MUST be a reference to it.

gadgets.Tab: Methods return an "Element" type. What is an "Element"? Is it an HTMLElement? A dom reference? Some new Element object that we're defining elsewhere?

gadgets.getCallback (and others): Method returns a "Function". No implementations return objects with "Function" in the prototype chain for these calls, they all return anonymous functions. What are the signatures of these functions that are returned?

Several references to <static> What does this mean? Javascript has no notion of "static" functions. How do I invoke this? Is it special in some way?

All the enumeration-like objects have their values missing. The values must be well defined as well as the keys, otherwise it simply won't work.

Several references to Map.<something, something> What does this mean? What is a "Map" in javascript?

What is a "Static Class"?

gadgets.io.MethodType: "Used by RequestParameters" -- In what way? Does it do magic tricks?

Lots of references to "not supported by all containers". This is supposed to be a specification -- it needs to specify whether the feature is required or not.

REFRESH_INTERVAL: Contradicts the xml spec that says that the server has discretion over caching behavior. Needs to be explicit about what this actually does. HTTP cache control headers? Server-side caching? What does "may not be cached" mean? How can I sign a call to getProxyUrl in the first place?

ContentType.FEED: "Returns a json representation of a feed". What is a "feed"? Can I use genetically engineered corn?

gadgets.skins.Property.FONT_COLOR: "The color that the main font should use". This doesn't make sense. How does a font "use" a color? What if I use 5 different fonts in my gadget?

gadgets.util.escapeString: How does this "make it safer"? Does it install anti-lock brakes or something?

gadgets.util.getFeatureParameters: "Gets the feature parameters" -- What feature parameters? Does this somehow relate to The "feature" attribute of <Require> tags? That should be mentioned.

gadgets.util.hasFeature: "...whether the current feature is supported" -- What is the "current feature"? Is there some sort of concurrency issue that might change what the "current" feature is?

gadgets.util.registerOnLoadHandler: "registers an onload handler" -- And does what with it? What's an "onload handler"?

gadgets.views.View.isOnlyVisibleGadget: "On a canvas page or in maximize mode this is most likely true; on a profile page or in dashboard mode, it is most likely false." -- What is "maximized mode" and what is "dashboard mode"? What's a "canvas page"? What's a "profile page"? Suggest explaining these notions in the gadget spec XML.

[Zhen Wang]

The function signature of gadgets.rpc.unsubscribe should be
unsubscribe(channelName). No callback parameter is required.

On Fri, May 9, 2008 at 6:38 PM, Dan Peterson <dpet...@google.com> wrote:

[Zhen Wang]

Oops. I meant gadgets.pubsub.unsubscribe.

[Zhen Wang]

jsdoc seems inadequate to document types at such a fine-grained level.

[Paul Lindner]

I'm in general agreement with what Kevin mentions below. We need to
be painfully rigourous in our definitions. I have a few comments
below, but also:

* Didn't we agree that REFRESH_INTERVAL is for
gadgets.io.RequestParameters?

I think that was what led to the confusion about signed requests and
post data in the REFRESH_INTERVAL section for getProxyUrl()

Also, I believe that REFRESH_INTERVAL should take precedence over any
HTTP standard methods of cache control. This is especially important
if a gadget developer is caching an object on a server that she/he
does not control.

I also think we should go through every single call here and document
the expected behavior when errors or null values are present.

Also a few specific notes:

gadgets.io.AuthorizationType.SIGNED should reference the signing
protocol.

In general can we get more expressive language for the makeRequest
docs? This doc for the old _IG_* methods is a pretty good source:

http://code.google.com/apis/gadgets/docs/remote-content.html

> > From: Dan Peterson <dpet...@google.com>
> > Date: Fri, May 9, 2008 at 6:27 PM
> > Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related
> > spec updates
> > To: opensocial-and-gadgets-spec <
> > opensocial-an...@googlegroups.com>
> >
> >
> > Hi folks,
> >
> > As discussed last week, the full draft of OpenSocial v0.8 specification is
> > ready for your review. This draft specification includes updates to existing
> > specs, inclusion of the RESTful spec, release notes, and detailed JavaScript
> > doc (JSDoc). The intent was to clearly capture all of the 40+
> > changes/additions that we have developed on this mailing list since version
> > 0.7 of the spec (as tracked in
> > http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ).
> > Let's use the next week or two to make improvements to these docs and then
> > we can lock down 0.8.
> >
> > You can find all 6 of these documents uploaded into the "Files" section of
> > this Google Group:
> > http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name
> >
> > The draft documents published are (please note that some of the links in
> > the files might not work as this is only a staged copy):
> >

> > - 1 - OpenSocial 0.8 Release Notes
> > - 2 - OpenSocial 0.8 Specification
> > - 3 - OpenSocial 0.8 RESTful API Specification
> > - 4 - gadgets Specification
> > - Canonical gadgets XSD
> > - Extended gadgets XSD
> > - gadgets Message Bundle XSD
> > - 5 - opensocial.* 0.8 JS doc
> > - 6 - gadgets.* JS doc

> >
> > I have conveniently numbered these documents so it is easier for you to
> > walk through them in a clear order. In addition, documents 1 through 4 have
> > their additions/updates highlighted for ease of reference. To better
> > organize detailed feedback for each document, I will now start a thread for
> > each of the 6 documents. Please be sure to direct your feedback to the
> > appropriate thread.
> >
> > Also, as a reminder, this coming Wednesday, May 15, we'll be holding an
> > OpenSocial Summit in Mountain View, California. This event is an ideal
> > opportunity to discuss this draft specification, propose ideas for future
> > iterations, and learn about the latest happenings in the community -- as
> > well as get to know each other in person.
> >
> > You can learn more about the event at:
> > http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
> > The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
> > (RSVP is here:
> > http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )
> >
> > Looking forward to your feedback (in the appropriate thread ;),
> > -Dan
> >
> >
> >
> > >
> >
>

> You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
> To post to this group, send email to opensocial-an...@googlegroups.com
> To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com
> For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> -~----------~----~----~----~------~----~------~--~---
>

--
Paul Lindner ||||| | | | | | | | | |
lin...@inuus.com

[Dan Peterson]

Thanks, Kevin -- lots of good feedback here, making the spec better. These issues have been handled.

-Dan

On Sat, May 10, 2008 at 2:36 AM, Kevin Brown <et...@google.com> wrote:

[Dan Peterson]

Nice catch -- fixed!