Overall, I'm happy with the changes. I went ahead and tested all of the
links, and noted where they point to missing information. For all I
know, those could be intentional because the docs are still in a
transitional state, but I thought it would be a good idea to catalog
them all to be sure that they get fixed up eventually.
http://codereview.appspot.com/157078/diff/9/2002
File Social-Gadget.xml (right):
http://codereview.appspot.com/157078/diff/9/2002#newcode43
Social-Gadget.xml:43: <section title="JavaScript API Reference"
This seems to be missing APIs for Albums and MediaItems.
http://codereview.appspot.com/157078/diff/9/2002#newcode58
Social-Gadget.xml:58: <t hangText="Returns">A <eref
target="Core-Gadget.xml#osapi.Request">osapi.Request</eref> to retrieve
information from the People service. Executing this request MUST return
a <eref target="./Social-Data.xml#Person">Person</eref> object or a
<eref target="./Core-Data.xml#Collection">Collection</eref> of <eref
target="./Social-Data.xml#Person">Person</eref> objects.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode83
Social-Gadget.xml:83: <t hangText="Returns">A <eref
target="Core-Gadget.xml#osapi.Request">osapi.Request</eref> to retrieve
information from the People service. Executing this request MUST return
a <eref target="./Core-Data.xml#Collection">Collection</eref> of <eref
target="./Social-Data.xml#Person">Person</eref> objects representing the
viewer's friends.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode108
Social-Gadget.xml:108: <t hangText="Returns">A <eref
target="Core-Gadget.xml#osapi.Request">osapi.Request</eref> to retrieve
information from the People service. Executing this request MUST return
a <eref target="./Core-Data.xml#Collection">Collection</eref> of <eref
target="./Social-Data.xml#Person">Person</eref> objects representing the
owner's friends.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode178
Social-Gadget.xml:178: <t hangText="Returns">A <eref
target="Core-Gadget.xml#osapi.Request">osapi.Request</eref> to retrieve
information from the Activities service. Executing this request MUST
return a <eref target="./Social-Data.xml#Activity">Activity</eref>
object or a <eref target="./Core-Data.xml#Collection">Collection</eref>
of <eref target="./Social-Data.xml#Activity">Activity</eref>
objects.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode323
Social-Gadget.xml:323: <eref
target="./Social-API-Server.xml#Messages-Service">Messages
service</eref>.</t>
Just FYI, this section is completely missing from the
Social-API-Server.xml document (most others have at least a stub
heading).
http://codereview.appspot.com/157078/diff/9/2002#newcode355
Social-Gadget.xml:355: <t>Namespace for top-level people functions.</t>
This whole section is a little inconsistent about where it puts the
xrefs. Sometimes in the method signature, sometimes in the
parameters/returns type column, sometimes in the description column,
sometimes all, sometimes none.
I think it would be best to just chose one location and fix up the
section to use that one consistently. It doesn't really matter which you
choose, but all else equal I would say put them in the Type column,
surrounding the type names there.
http://codereview.appspot.com/157078/diff/9/2002#newcode449
Social-Gadget.xml:449: have its error code set to NOT_IMPLEMENTED.</t>
Does this mean the string "NOT_IMPLEMENTED"? If so, it should be
explicit and say 'the String "NOT_IMPLEMENTED"'. If it refers to a
constant that's defined somewhere, it should xref the constant.
http://codereview.appspot.com/157078/diff/9/2002#newcode465
Social-Gadget.xml:465: <c>Function</c>
Since we use a pseudo-generic syntax for types elsewhere, I think it
would be convenient to define the return and parameter types for any
Function parameters. Something like 'void
Function(opensocial.ResponseItem)' (with appropriate xrefs inserted as
necessary).
http://codereview.appspot.com/157078/diff/9/2002#newcode493
Social-Gadget.xml:493: error code set to NOT_IMPLEMENTED.</t></t>
Same comment as with requestPermission, above.
http://codereview.appspot.com/157078/diff/9/2002#newcode509
Social-Gadget.xml:509: <c>Function</c>
Same comment as with opt_callback in requestPermission, above.
http://codereview.appspot.com/157078/diff/9/2002#newcode758
Social-Gadget.xml:758: <t>The Social Gadget Specification extends the
Data Pipelining capabilities of the Core Gadget Specification by adding
suport for the following tags:</t>
It would be helpful to link to the relevant section/document here.
(Core-Gadget.xml#rfc.section.5)
http://codereview.appspot.com/157078/diff/9/2002#newcode765
Social-Gadget.xml:765: <t hangText="Returns">A <eref
target="./Social-Data.xml#Person">Person</eref> object or a <eref
target="./Core-Data.xml#Collection">Collection</eref> of <eref
target="./Social-Data.xml#Person">Person</eref> objects.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode795
Social-Gadget.xml:795: <t hangtext="Returns">A <eref
target="./Social-Data.xml#Activity">Activity</eref> object or a <eref
target="./Core-Data.xml#Collection">Collection</eref> of <eref
target="./Social-Data.xml#Activity">Activity</eref> objects.</t>
Should be <eref
target="./Core-Data.xml#OpenSocial-Collection">Collection</eref>
(different hash)
http://codereview.appspot.com/157078/diff/9/2002#newcode805
Social-Gadget.xml:805: <section title="Templating">
I'm a little unclear... are OpenSocial-Markup-Language-Tags.xml and
OpenSocial-Templating.xml going away? This section doesn't make a lot of
sense to me here.
http://codereview.appspot.com/157078/diff/9/2002#newcode1092
Social-Gadget.xml:1092: <reference anchor='OAuth-Core-1.0'
I don't see a reference to this in the rest of the document. If we're
going to reference the OAuth spec, I think we should reference revision
A (
http://oauth.net/core/1.0a) which contains an important security fix.
http://codereview.appspot.com/157078/diff/9/2002#newcode1178
Social-Gadget.xml:1178: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.cache.invalidate">osapi.cache.invalidate()</eref>
instead.</t>
This link doesn't exist in the specified document, and that method isn't
specified in this document either. Is that a planned addition?
http://codereview.appspot.com/157078/diff/9/2002#newcode1227
Social-Gadget.xml:1227: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Album">Album</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Note: Album is still missing from the linked document.
http://codereview.appspot.com/157078/diff/9/2002#newcode1257
Social-Gadget.xml:1257: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.newBatch">osapi.newBatch()</eref>
instead.</t>
Should link to Core-Gadget.xml#osapi.newBatch
http://codereview.appspot.com/157078/diff/9/2002#newcode1372
Social-Gadget.xml:1372: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.activities.create">osapi.activities.create()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.activities.create
http://codereview.appspot.com/157078/diff/9/2002#newcode1416
Social-Gadget.xml:1416: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.messages.send">osapi.messages.send()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.messages.send
http://codereview.appspot.com/157078/diff/9/2002#newcode1452
Social-Gadget.xml:1452: <eref
target="./OpenSocial-Specification.xml#opensocial.NavigationParameters.DestinationType">
Should link to
Social-Gadget.xml#opensocial.NavigationParameters.DestinationType
http://codereview.appspot.com/157078/diff/9/2002#newcode1458
Social-Gadget.xml:1458: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.mediaItems.create">osapi.mediaItems.create()</eref>
instead.</t>
This method doesn't seem to exist.
http://codereview.appspot.com/157078/diff/9/2002#newcode1867
Social-Gadget.xml:1867: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Album">Album</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Another broken link to the missing Album definition
http://codereview.appspot.com/157078/diff/9/2002#newcode1922
Social-Gadget.xml:1922: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Album">Album</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Another broken link to the missing Album definition
http://codereview.appspot.com/157078/diff/9/2002#newcode1981
Social-Gadget.xml:1981: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref
target="./Social-Data.xml#BodyType">BodyType</eref> objects introduced
in OpenSocial v1.0 instead.</t>
There isn't currently a BodyType object defined in that document. The
description of Person.bodyType says that it's a string. It's not totally
clear to me how the 0.8 enum field types map to the new objects. Right
now it kind of implies that this field can accept any string value.
http://codereview.appspot.com/157078/diff/9/2002#newcode2016
Social-Gadget.xml:2016: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref
target="./Social-Data.xml#BodyType">BodyType</eref> objects introduced
in OpenSocial v1.0 instead.</t>
Another broken link to BodyType
http://codereview.appspot.com/157078/diff/9/2002#newcode2056
Social-Gadget.xml:2056: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref
target="./Social-Data.xml#Collection">Collection</eref> objects
introduced in OpenSocial v1.0 instead.</t>
Should link to Core-Data.xml#OpenSocial-Collection
http://codereview.appspot.com/157078/diff/9/2002#newcode2181
Social-Gadget.xml:2181: <t><x:highlight>Deprecated.</x:highlight>
Service requests should be represented using the <eref
target="./OpenSocial-Specification.xml#osapi.BatchRequest">Batch
Request</eref> JSON object.</t>
Should link to Core-Gadget.xml#osapi.BatchRequest
http://codereview.appspot.com/157078/diff/9/2002#newcode2234
Social-Gadget.xml:2234: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.albums.create">osapi.albums.create()</eref>
instead.</t>
The linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2262
Social-Gadget.xml:2262: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.mediaItems.create">osapi.mediaItems.create()</eref>
instead.</t>
The linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2291
Social-Gadget.xml:2291: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.albums.delete">osapi.albums.delete()</eref>
instead.</t>
The linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2317
Social-Gadget.xml:2317: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.activities.get">osapi.activities.get()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.activities.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2345
Social-Gadget.xml:2345: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.albums.get">osapi.albums.get()</eref>
instead.</t>
The linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2377
Social-Gadget.xml:2377: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.mediaItems.get">osapi.mediaItems.get()</eref>
instead.</t>
The linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2413
Social-Gadget.xml:2413: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.people.get">osapi.people.get()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.people.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2444
Social-Gadget.xml:2444: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.appdata.get">osapi.appdata.get()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.appdata.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2481
Social-Gadget.xml:2481: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.people.get">osapi.people.get()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.people.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2513
Social-Gadget.xml:2513: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.appdata.delete">osapi.appdata.delete()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.appdata.delete
http://codereview.appspot.com/157078/diff/9/2002#newcode2537
Social-Gadget.xml:2537: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.albums.update">osapi.albums.update()</eref>
instead.</t>
Linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2568
Social-Gadget.xml:2568: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.mediaItems.update">osapi.mediaItems.update()</eref>
instead.</t>
Linked method is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode2605
Social-Gadget.xml:2605: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.appdata.update">osapi.appdata.update()</eref>
instead.</t>
Should link to Social-Gadget.xml#osapi.appdata.update
http://codereview.appspot.com/157078/diff/9/2002#newcode2634
Social-Gadget.xml:2634: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.Request.execute">osapi.Request.execute()</eref>
or <eref
target="./OpenSocial-Specification.xml#osapi.BatchRequest.execute">osapi.BatchRequest.execute()</eref>instead.</t>
Should link to Core-Gadget.xml#osapi.Request.execute and
Core-Gadget.xml#osapi.BatchRequest.execute
http://codereview.appspot.com/157078/diff/9/2002#newcode2656
Social-Gadget.xml:2656: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.activities.get">osapi.activities.get()</eref>
with the startIndex, startPage, and count parameters to handle
paging.</t>
Should link to Social-Gadget.xml#osapi.activities.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2671
Social-Gadget.xml:2671: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.albums.get">osapi.albums.get()</eref>
with the startIndex, startPage, and count parameters to handle
paging.</t>
Link to missing method
http://codereview.appspot.com/157078/diff/9/2002#newcode2701
Social-Gadget.xml:2701: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.people.get">osapi.people.get()</eref>
with the filterBy, filterOp, and filterValue parameters to filter the
people objects returned.</t>
Should link to Social-Gadget.xml#osapi.people.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2734
Social-Gadget.xml:2734: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.mediaItems.get">osapi.mediaItems.get()</eref>
with the startIndex, startPage, and count parameters to handle
paging.</t>
Link to missing method
http://codereview.appspot.com/157078/diff/9/2002#newcode2749
Social-Gadget.xml:2749: <list style="hanging">
Several links in the list below should be pointed to
Social-Gadget.xml#osapi.people.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2811
Social-Gadget.xml:2811: <t><x:highlight>Deprecated.</x:highlight> Use
<eref
target="./OpenSocial-Specification.xml#osapi.people.get">osapi.people.get()</eref>
with the sortOrder parameter to specify the sort order.</t>
Should link to Social-Gadget.xml#osapi.people.get
http://codereview.appspot.com/157078/diff/9/2002#newcode2829
Social-Gadget.xml:2829: <t><x:highlight>Deprecated.</x:highlight>
Callback methods receive <eref
target="./Social-Data.xml#Response">Response</eref> objects.</t>
Should link to Core-Data.xml#Response
http://codereview.appspot.com/157078/diff/9/2002#newcode2892
Social-Gadget.xml:2892: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Email">Email</eref>
objects introduced in OpenSocial v1.0 instead.</t>
There's no Email object. Looks like the emails field on Person is
defined as a "Plural-Field <string>" now.
http://codereview.appspot.com/157078/diff/9/2002#newcode2927
Social-Gadget.xml:2927: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Email">Email</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Another link to missing Email object
http://codereview.appspot.com/157078/diff/9/2002#newcode4460
Social-Gadget.xml:4460: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Phone">Phone</eref>
objects introduced in OpenSocial v1.0 instead.</t>
There's currently no new Phone object defined. The Person.phoneNumbers
field is defined as Plural-Field <string>
http://codereview.appspot.com/157078/diff/9/2002#newcode4495
Social-Gadget.xml:4495: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Phone">Phone</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Another link to missing Phone object
http://codereview.appspot.com/157078/diff/9/2002#newcode4516
Social-Gadget.xml:4516: <t><x:highlight>Deprecated.</x:highlight>
Callback methods receive <eref
target="./Social-Data.xml#Response">Response</eref> objects.</t>
Response object is missing.
http://codereview.appspot.com/157078/diff/9/2002#newcode4590
Social-Gadget.xml:4590: <t><x:highlight>Deprecated.</x:highlight>
Callback methods receive <eref
target="./Social-Data.xml#Response">Response</eref> objects.</t>
Response object is missing
http://codereview.appspot.com/157078/diff/9/2002#newcode4621
Social-Gadget.xml:4621: <eref
target="./OpenSocial.xml#opensocial.requestPermission">
Should link to Social-Gadget.xml#opensocial.requestPermission
http://codereview.appspot.com/157078/diff/9/2002#newcode4629
Social-Gadget.xml:4629: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Url">Url</eref>
objects introduced in OpenSocial v1.0 instead.</t>
There's no new Url object. URLs are represented as strings according to
the current docs.
http://codereview.appspot.com/157078/diff/9/2002#newcode4664
Social-Gadget.xml:4664: <t><x:highlight>Deprecated.</x:highlight> Use
the definition of <eref target="./Social-Data.xml#Url">Url</eref>
objects introduced in OpenSocial v1.0 instead.</t>
Another link to the missing Url object
http://codereview.appspot.com/157078