Browser API reference: how can we keep it up to date?

[Paul Rouget]

Until recently, the Browser API had only one consumer (Gaia) and one
implementation (Gecko).

Now we have a new consumer (browser.html) and a new implementation on
its way (Servo).

The Browser API has no reference (MDN page is not up to date, and the
WebIDL only list methods, leaving out all the events), so I dug into
the implementation, and collected all the information I could find
about the methods, events and behavior of the Browser API in a single
document:

https://github.com/paulrouget/mozBrowserAPI/blob/master/BrowserAPI.md
(please help me review it, I haven’t verified everything, and there’s
still some FIXMEs)

Having a central reference would help keeping in sync the 2
implementations and make documenting the API easier. We also want to
suggest some changes to the API, and having such a reference will help
a lot while discussing these changes.

My question is: how can we keep this reference up to date? Maybe we
could add this document to m-c, and ask reviewers to require the
document to be updated? Or maybe add the comments to the WebIDL and
somehow include the list of authorized events with a definition of
their `details` property into the WebIDL?


-- Paul

[Chris Mills]

> On 15 Sep 2015, at 09:41, Paul Rouget <pa...@mozilla.com> wrote:
>
> Until recently, the Browser API had only one consumer (Gaia) and one
> implementation (Gecko).
>
> Now we have a new consumer (browser.html) and a new implementation on
> its way (Servo).
>
> The Browser API has no reference (MDN page is not up to date, and the
> WebIDL only list methods, leaving out all the events), so I dug into
> the implementation, and collected all the information I could find
> about the methods, events and behavior of the Browser API in a single
> document:
>
> https://github.com/paulrouget/mozBrowserAPI/blob/master/BrowserAPI.md
> (please help me review it, I haven’t verified everything, and there’s
> still some FIXMEs)
>

This is really useful Paul - thanks. I feel bad that the Firefox OS APIs are not more up to date on MDN, but we are drowning in documentation work.

> Having a central reference would help keeping in sync the 2
> implementations and make documenting the API easier.

Yup, having this available for each API would make the job of getting this documented on MDN a lot quicker.

> We also want to
> suggest some changes to the API, and having such a reference will help
> a lot while discussing these changes.

This is one reason why documenting Firefox OS is hard - we are drowning in work as it is, even without the APIs changing all the time (I appreciate that it is necessary, but it doesn’t make it any easier ;-) )

>
> My question is: how can we keep this reference up to date? Maybe we
> could add this document to m-c, and ask reviewers to require the
> document to be updated? Or maybe add the comments to the WebIDL and
> somehow include the list of authorized events with a definition of
> their `details` property into the WebIDL?
>

If I could just watch this reference for changes and then make the corresponding updates on MDN, this would be a dream come true.

Ummm, can we do this for every FxOs API? ;-)

>
> -- Paul
> _______________________________________________
> dev-b2g mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-b2g

[Paul Rouget]

On Tue, Sep 15, 2015 at 11:22 AM, Chris Mills <cmi...@mozilla.com> wrote:
> If I could just watch this reference for changes and then make the corresponding updates on MDN, this would be a dream come true.

This is one of the reason I put this document together.

I believe the WebIDL files should play this role. But they are missing
comments and events.

> Ummm, can we do this for every FxOs API? ;-)

As APIs get implemented in Servo, we’ll need references like this one.

-- Paul

[Ehsan Akhgari]

On 2015-09-15 7:31 AM, Paul Rouget wrote:
> I believe the WebIDL files should play this role. But they are missing
> comments and events.

WebIDL files are not a suitable place for documentation to live, since
they require review from DOM peers who are typically overloaded
individuals, and it would be nice to not make them review documentation
changes.

I don't understand why the dev-doc-needed based workflow that we use to
document other parts of the Web platform is insufficient for this API.

[Paul Rouget]

Other parts of the web platforms usually have a reference: the
specification. So there’s a minimal documentation already available.
Which is not the case with the API with no standardization efforts,
like the Browser API.

And we can’t use dev-doc-needed to keep a reference up to date (too
often, we forget about the flag, and like Chris said, the MDN editors
are very busy too), and that’s clearly the responsibility of the
developer, not of the MDN team.


-- Paul

[Tim Guan-tin Chien]

I agree with Paul. We should try to expose the event properties and
stuff with defined WebIDL interface instead of Cu.cloneInto(). FWIW, I
am trying to do that in bug 1197700 etc. for mozInputMethod API.

However, just like everything related to B2G, I am not sure about the
priorities on this.

(CC'ing Kanru -- we actually talked about this a few weeks ago offline)


Tim

[Fabrice Desré]

On 09/15/2015 07:24 AM, Ehsan Akhgari wrote:
> On 2015-09-15 7:31 AM, Paul Rouget wrote:
>> I believe the WebIDL files should play this role. But they are missing
>> comments and events.
>
> WebIDL files are not a suitable place for documentation to live, since
> they require review from DOM peers who are typically overloaded
> individuals, and it would be nice to not make them review documentation
> changes.

That's also not where localizers expect to find their reference
material, and not where they could publish translations.

Fabrice
--
Fabrice Desré
b2g team
Mozilla Corporation

[J. Ryan Stinnett]

On Tue, Sep 15, 2015 at 9:47 AM, Paul Rouget <pa...@mozilla.com> wrote:
> And we can’t use dev-doc-needed to keep a reference up to date (too
> often, we forget about the flag, and like Chris said, the MDN editors
> are very busy too), and that’s clearly the responsibility of the
> developer, not of the MDN team.

Even with these caveats, it still might be worth setting
dev-doc-needed when you remember, so it's tracked as a thing to do at
least.

Maybe the dev does it or maybe the docs team, but I think it would at
least increase the chances of doc completion.

- Ryan

[Paul Rouget]

WebIDL should not replace the documentation. I’m saying WebIDL could
play the role of a specification, a reference. You need something to
start documenting an API. MDN editors can’t just guess what methods do
and what events exist. HTML and Web APIs have a specification. The
browser API has nothing.

Maybe WebIDL is not the right place. I actually don’t care where this
lives. But we need a reference/spec. Otherwise, the documentation will
always be behind, and the Servo implementation will diverge. And if
this reference is outside of m-c, we should, somehow, enforce updating
the reference when events/methods are added/removed/modified.

Any suggestion?

--
Paul

[Paul Rouget]

On Tue, Sep 15, 2015 at 5:20 PM, Tim Guan-tin Chien
<timd...@mozilla.com> wrote:
> I agree with Paul. We should try to expose the event properties and
> stuff with defined WebIDL interface instead of Cu.cloneInto(). FWIW, I
> am trying to do that in bug 1197700 etc. for mozInputMethod API.
>
> However, just like everything related to B2G, I am not sure about the
> priorities on this.

I’m willing to spend on improving the situation.

-- Paul

[Paul Rouget]

*spend some time

--
Paul

[Fabrice Desré]

On 09/15/2015 09:00 AM, Paul Rouget wrote:

> Any suggestion?

I don't see any issue with using what you started on github as a
reference, and adding comments in the implementation to remind people
that they need to update the doc when making observable changes.

[Chris Mills]

> On 15 Sep 2015, at 17:37, Fabrice Desré <fab...@mozilla.com> wrote:
>
> On 09/15/2015 09:00 AM, Paul Rouget wrote:
>
>> Any suggestion?
>
> I don't see any issue with using what you started on github as a
> reference, and adding comments in the implementation to remind people
> that they need to update the doc when making observable changes.

I think creating some kind of document like Paul’s for Firefox OS APIs would be a great start towards getting documentation done more rapidly and effectively. Ideally i’d like:

* WebIDL
* Some notes to explain what the members do
* A couple of brief code examples to get me started on writing demos
* A designated point of contact to bug with questions ;-)

Sometimes similar documents are published at, https://wiki.mozilla.org/WebAPI, and these are sometimes helpful, but not always.

The implementation bugs are rarely helpful, as there is so much dense information there. I often just end up looking at the webidl files on dxr, and guessing until I can find an engineer to bug for info (not too hard - most of you are super helpful! But I appreciate you are crazy busy too.)

If producing a doc like Paul’s was in the workflow, I could just monitor that for changes, and all would be great.

In terms of getting updates into the docs workflow, adding the dev-doc-needed keyword is really useful. At a push, it would be useful to just file a developer documentation bug saying “this API’s docs are really outdated. Please fix”, or similar. At least then they would show up on our map.

[Ehsan Akhgari]

On 2015-09-15 10:47 AM, Paul Rouget wrote:
> Other parts of the web platforms usually have a reference: the
> specification. So there’s a minimal documentation already available.
> Which is not the case with the API with no standardization efforts,
> like the Browser API.
>

> And we can’t use dev-doc-needed to keep a reference up to date (too
> often, we forget about the flag, and like Chris said, the MDN editors
> are very busy too), and that’s clearly the responsibility of the
> developer, not of the MDN team.

I am not sure who "the developer" you're referring to is, but presumably
you can ask them to update an MDN page. My point was that the WebIDL
file is not the right place for either specification language or
documentation language.