Re: Documenting APIs and bug #15

Hi all,

We've got a fix live, although we've got an extra clean-up task now on our
collective to-do lists.

Some quick background: The syntax is generated using a semantic mediawiki
query of all the parameter properties set on a given page.  These
properties are set by the template used to print out the list of parameter
descriptions, and each one creates a "subobject" with its own properties
(name, required, description).

When it prints the property list to the page, that's just a simple series
of template calls, so they are printed in the order the data was declared
in the form.  However, when it uses the query to get the list of names,
they are returned in an arbitrary order based on database hashcode id
values.  You can sort the query, but only based on a specific property of
the subobject, not by the original order in which the properties were
declared.  So we need to create a property of each subobject that defines
the index of that argument in the method call.

I was unable to figure out any way to get Semantic MediaWiki to insert an
auto-incremented counter for each instance of the parameter subobject.
 Instead, I've added a field to the form where you can explicitly specify
the index.

So, in order to get the syntax to print out with all the parameters in the
correct order, we'll need to go through and edit each page to manually type
in "0", "1", "2" in the forms.  Good thing we were already planning to do a
massive stock-check of all pages in the wiki, right?

In the meantime, for all pages where index values have *not* been set for
the API parameters, the syntax will print like this:

    var result = object.arcTo(*see parameter list*);

(if there are no parameters, it will just print with empty brackets as
expected).

Once parameter index values are set, it looks like this:

var result = object.arcTo(x1, y1, x2, y2, radius);


However, if you're editing pages, be aware that "Show Preview" will NOT
display the syntax properly until after your changes have been saved.
 That's because the query results in the preview will be based on the
*current* state of the wiki, not based on the unsaved changes you've made.

Also be aware that if you set index values for some but not all of the
parameters, only those ones will show up int the syntax block.  All or
nothing, please.

Thanks to everyone else who was tossing ideas around here and on IRC.
 Thanks especially to Dominique for hitting us over the head with the
problem.

NOW:  Who wants to go through the Bug Tracker and figure out which issues
this closes and what is still left to do?

...Amelia

P.S.  For reference, the new/changed pages are

* http://docs.webplatform.org/wiki/Property:Parameter_index
* http://docs.webplatform.org/wiki/Template:Method_Parameter
* http://docs.webplatform.org/wiki/Form:API_Object_Method
* http://docs.webplatform.org/wiki/Template:API_Object_Method



On 7 May 2014 17:46, Eliezer Bernart <eliezer.bernart@gmail.com> wrote:

> Hey Folks,
>
> I just updated the CSS Property template to make the list of Syntax
> section (only for the CSS properties pages) be alphabetically ordered. I
> added two parameters to the #ask query [1].
>
> http://project.webplatform.org/tmpl/issues/16
>
> If the alphabetic order do not looks good, let us know.
>
> Now I'll try to help Amelia on the API Object Template.
>
> [1]
> http://docs.webplatform.org/w/index.php?title=Template:CSS_Property&diff=52872&oldid=39966
>
>
>
>
> Eliezer
>
> @eliezerbernart
> eliezerb
>
>
> On Wed, May 7, 2014 at 7:58 PM, Renoir Boulanger <renoir@w3.org> wrote:
>
>> Hi all,
>>
>> I just spent some time looking around SMW and how #ask works a little
>> bit. We also have AmeliaBR who is having a look at the moment.
>>
>> My research isn't deep, but here's my feeling:
>>
>> * Properties are sorted by default by ascending order by default. Since
>> there are no 'order' property in the document I saw (1) its might be in
>> that order
>> * Which field is it ordering from? I don’t know that. Maybe in property
>> insert id in the database... e.g. if you have many property inserted in
>> random order and you need to pick and choose... we are doomed!
>>
>> That's where I would have a look. Hopefully Elizer, or Amelia will be
>> able to work it out :)
>>
>>   [0]: http://semantic-mediawiki.org/wiki/Help:Special:Ask
>>   [1]: http://semantic-mediawiki.org/wiki/Help:Inline_queries
>>   [2]: http://docs.webplatform.org/upgrade/Special:Ask
>>
>> On 2014-05-07, 10:23 AM, Doug Schepers wrote:
>> > Hi, folks–
>> >
>> > I'm not a template expert, and I'd happily defer to Eliezer, Amelia,
>> > Garbee, or pretty much anyone else who knows anything about templates.
>> >
>> > Regards-
>> > -Doug
>> >
>> > On 5/7/14 1:17 PM, Julee Burdekin wrote:
>> >> Hi, Eliot: This effects all docs that use the parameter fields.
>> >> That’s why
>> >> I transferred it to the templates project. The template project owner
>> >> was
>> >> Alex, but given the fact that Doug is deciding priority of all
>> >> infrastructure work at this point, I think Doug should fold it into the
>> >> workload. J
>> >>
>> >> -------------------
>> >> Julee Burdekin
>> >> Content Strategist
>> >> Adobe Web Platform
>> >> @adobejulee
>> >> julee@adobe.com
>> >>
>> >>
>> >>
>> >>
>> >>
>> >> On 5/7/14, 9:34 AM, "Eliot Graff" <Eliot.Graff@microsoft.com> wrote:
>> >>
>> >>> Wow. I was blissfully unaware of this issue. It's a ship-stopper. We
>> >>> can't have docs that produce syntax that is unusable.
>> >>>
>> >>> Who would be the right person to own and drive this? Currently there
>> is
>> >>> no owner.
>> >>>
>> >>> Also, do we have a handle on how many topics are affected by this? I
>> >>> gather from the bug comments that it is all of the Canvas 2D API
>> >>> members.
>> >>> Any others?
>> >>>
>> >>> Thanks,
>> >>>
>> >>> Eliot
>> >>>
>> >>>> -----Original Message-----
>> >>>> From: Dominique Hazael-Massieux [mailto:dom@w3.org]
>> >>>> Sent: Wednesday, May 7, 2014 8:34 AM
>> >>>> To: Renoir Boulanger
>> >>>> Cc: Eliezer Bernart; public-webplatform@w3.org
>> >>>> Subject: Re: Documenting APIs and bug #15
>> >>>>
>> >>>> Le mercredi 07 mai 2014 à 08:12 -0700, Renoir Boulanger a écrit :
>> >>>>> Indeed, its a big issue and I forgot about that one.
>> >>>>>
>> >>>>> Can you tell me if it gets improved when you try on the /upgrade/
>> >>>> namespace?
>> >>>>
>> >>>> It isn't unfortunately.
>> >>>>
>> >>>>> I'm not working on templating issues these days, but maybe somebody
>> >>>>> else
>> >>>>> (Eliezer?) would find something to do?
>> >>>>>
>> >>>>>    [0]:
>> >>>>> http://docs.webplatform.org/upgrade/dom/Navigator/getUserMedia
>> >>>>
>> >>>> Dom
>> >>>>
>> >>>>
>> >>>
>> >>
>> >
>> >
>> >
>>
>> --
>> Regards,
>>
>> Renoir Boulanger  |  Developer operations engineer
>> W3C  |  Web Platform Project
>>
>> http://w3.org/people/#renoirb  ✪  https://renoirboulanger.com/  ✪
>>  @renoirb
>> ~
>>
>>
>>
>