Re: Documenting APIs and bug #15

Hey, Amelia–

Great job!

I agree, let's put "add indexes to parameters" to our task list for when 
we walk through and catalog all the pages, flip ready-flags, etc.

Regards-
-Doug

On 5/7/14 10:21 PM, Amelia Bellamy-Royds wrote:
> 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
> <mailto: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
> <mailto: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 <mailto:julee@adobe.com>
>>>
>>>
>>>
>>>
>>>
>>> On 5/7/14, 9:34 AM, "Eliot Graff" <Eliot.Graff@microsoft.com
> <mailto: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
> <mailto:dom@w3.org>]
>>>>> Sent: Wednesday, May 7, 2014 8:34 AM To: Renoir Boulanger Cc:
>>>>> Eliezer Bernart; public-webplatform@w3.org
> <mailto: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 ~
>
>
>
>

Received on Thursday, 8 May 2014 07:42:46 UTC