1204977 - Browser API documentation needs updating

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: API: DOM, defect)

Description

[Chris Mills [:cmills]]

Paul has created a very useful comprehensive breakdown on Browser API functionality, including WebIDL, functionality descriptions and more.

https://github.com/paulrouget/mozBrowserAPI/blob/master/BrowserAPI.md

This will be very useful to help with updating this documentation, and keeping it updated in the future. I am hoping that this could act a good model for how we could deal with better documenting non-standard APIs in the future.

Comment 1

[Chris Mills [:cmills]]

I have finished documenting the Browser API, in terms of the state captured by Paul's doc.

This is basically complete, pending an editorial review by one of my colleagues, and a technical review by Paul.

I also had some questions to go along with the tech review:

* What are the defaults for download(), if the options are not specified? Where is the file saved, and how? Does it use DeviceStorage behind the scenes?
* When the hell does mozbrowseractivitydone fire? What is it used for? It's labelled as FIXME in your doc ;-)
* The mozbrowserlocationchange and mozbrowsererror events' objects still have a property of detail, rather than details, even thought it says details in your doc. A bit inconsistent.
* mozbrowsermetachange - I don't get why details.type is listed as optional — it is surely not settable by the user in any way, and there is surely no situation in which this wouldn't be useful information to provide? Also, if it isn't set in the <meta> tag or something, surely it would be returned as null, not just not returned, which is what "optional" seems to imply in your doc. Same comment for details.lang as well, really.
* mozbrowserresize/mozbrowserscroll/mozbrowserselectionstatechanged: I'm assuming the values are reported in device pixels? I'm sure this is the case in other places?
* mozbrowserselectionstatechanged: what values can the details.states property take? This is currently filled in as FIXME
* change/changed: some events end in 'change', some in 'changed', which seems inconsistent. Is there a good reason for this?

Comment 2

[Paul Rouget [:paul]]

(In reply to Chris Mills (Mozilla, MDN editor) [:cmills] from comment #1)
> * What are the defaults for download(), if the options are not specified?

filename is the filename in the url (http://foo.com/bar.jpeg -> bar.jpeg)

if referrer is not specified, there's no referrer.

> Where is the file saved, and how? Does it use DeviceStorage behind the
> scenes?

I'm not sure. See this function:
https://mxr.mozilla.org/mozilla-central/source/uriloader/exthandler/nsExternalHelperAppService.cpp#283

Apparently, /sdcard/download

> * When the hell does mozbrowseractivitydone fire? What is it used for? It's
> labelled as FIXME in your doc ;-)

I've never used that. Maybe ask someone in #gaia.
I guess it's fired when the next app has consumed the message.
For example, if you share a picture, and the user click on "email". The event is probably fired once the email has been sent. Or maybe when the email app opens.

> * The mozbrowserlocationchange and mozbrowsererror events' objects still
> have a property of detail, rather than details, even thought it says details
> in your doc. A bit inconsistent.

You're right. DOM events use "detail". I don't know why Browser's event use "details". It's unfortunate.

> * mozbrowsermetachange - I don't get why details.type is listed as optional
> — it is surely not settable by the user in any way, and there is surely no
> situation in which this wouldn't be useful information to provide? Also, if
> it isn't set in the <meta> tag or something, surely it would be returned as
> null, not just not returned, which is what "optional" seems to imply in your
> doc. Same comment for details.lang as well, really.

Yeah, by optional, I meant that the value can be "undefined".

> * mozbrowserresize/mozbrowserscroll/mozbrowserselectionstatechanged: I'm
> assuming the values are reported in device pixels? I'm sure this is the case
> in other places?

These are CSS pixels.

> * mozbrowserselectionstatechanged: what values can the details.states
> property take? This is currently filled in as FIXME

I don't know.

> * change/changed: some events end in 'change', some in 'changed', which
> seems inconsistent. Is there a good reason for this?

No good reason afaik :)