W3C home > Mailing lists > Public > public-webplatform@w3.org > May 2014

Re: Documenting APIs and bug #15

From: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com>
Date: Wed, 7 May 2014 08:31:57 -0600
Message-ID: <CAFDDJ7xETmWGns3urcFErUnyrpeL65TR69b_004wjZPmoXb9bA@mail.gmail.com>
To: Dominique Hazael-Massieux <dom@w3.org>
Cc: List WebPlatform public <public-webplatform@w3.org>
I agree this is a serious error.  Missing information is one thing,
blatantly incorrect information is another.

Until a solution for the syntax template can be fixed, maybe we should
suppress printing the syntax at all?  Or at least suppress it when there
are more than one parameters for a given method?

~ABR


On 7 May 2014 07:51, Dominique Hazael-Massieux <dom@w3.org> wrote:

> Hi,
>
> Bug #15 [1] highlights a killer bug for documenting APIs: it means that
> when you document the parameters of a given method, the parameters are
> not displayed in the correct order, making the documentation basically
> misleading.
>
> While the bug is reported on the canvas API, it applies really to any
> method documentation, making WPD pretty much unusable for documenting
> APIs.
>
> I've suggested a couple of possible approaches to fix this in [1] (none
> great unfortunately); but since I haven't seen much activity on this,
> and given how critical the bug seems to me, I thought I would raise
> attention to it on the list as well.
>
> Dom
>
> 1. http://project.webplatform.org/tmpl/issues/15
>
>
>
>
>
Received on Wednesday, 7 May 2014 14:32:26 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:21:01 UTC