Closed
Bug 1287421
Opened 8 years ago
Closed 8 years ago
Add "Return value" section consistently to all JavaScript reference docs
Categories
(Developer Documentation Graveyard :: JavaScript, defect, P5)
Tracking
(Not tracked)
RESOLVED
FIXED
People
(Reporter: fs, Unassigned, Mentored)
Details
:: Developer Documentation Request Request Type: Correction Gecko Version: unspecified Technical Contact: fscholz@mozilla.com :: Details Filing this as a mentored bug. As an experienced developer I want to see the possible return values of a JS function at a glance, so that I quickly go on coding in my editor with that specific piece of information. Issue brought up by Eduardo Bouças in https://twitter.com/eduardoboucas/status/754604419212308481 First sub task here is to find pages that are missing a short "Return value" section in the "Syntax" section. Find all JS pages here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Index or all objects here https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects Second sub task is to then go through and add the "Return value" sections. We can likely go through this by object. If anyone want to work on this bug, I propose to start by going through array pages https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array add "Return value" section and ask for review here. Step by step we will go through the rest. I will keep this bug updated for overall progress.
Reporter | ||
Updated•8 years ago
|
Mentor: fscholz
Comment 1•8 years ago
|
||
I would love to work on this. I made a start already and added a "Return value" section to the following pages: - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach I'm more than happy to keep going through pages and adding this section when missing, but I'd like to ask a few questions first, to make sure everyone is happy with the approach: 1) Can we standardise the title of this section to "Return value" on every page? Some pages call it "Returns" (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) 2) It would be good to also standardise the structure of the sentence used to describe the return value. In some pages it starts with "This functions returns..." (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some), whereas in others the value is listed straight away (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) — I personally prefer the latter, as the idea is for this section to be consumed at a glance. 3) Do we want to also ensure a "Parameters" section is always present, even if the function doesn't accept parameters? Some pages do this (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) Thanks!
Reporter | ||
Comment 2•8 years ago
|
||
(In reply to Eduardo Bouças from comment #1) > I would love to work on this. I made a start already and added a "Return > value" section to the following pages: > > - > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/every > - > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/pop > - > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/forEach I reviewed these 3 and they look great! Feel free to go ahead like this (and no need to request editorial review on every page if you feel confident). > > I'm more than happy to keep going through pages and adding this section when > missing, but I'd like to ask a few questions first, to make sure everyone is > happy with the approach: > > 1) Can we standardise the title of this section to "Return value" on every > page? Some pages call it "Returns" (e.g. > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/push) Yes, we agreed on "Return value" some months ago, but not all pages have been updated yet. > > 2) It would be good to also standardise the structure of the sentence used > to describe the return value. In some pages it starts with "This functions > returns..." (e.g. > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/some), whereas in others the value is listed straight > away (e.g. > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/push) — I personally prefer the latter, as the idea is > for this section to be consumed at a glance. Straight away like on push() seems OK to me, too. This is really about summary information. More details can be given in another section. > > 3) Do we want to also ensure a "Parameters" section is always present, even > if the function doesn't accept parameters? Some pages do this (e.g. > https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/ > Global_Objects/Array/pop) > I'm torn on this one. Sphinx or anyone else, any opinion? > Thanks! Thank you!
I personally don't appreciate the sections with only "None" which I feel useless (no info = nothing to say/display) Absence of parameters should be straightforward from the syntaxbox. If one need to programmatically analyze the content of such pages (you know, devtools... ;)) this should be pretty easy to deal with. Again, that's my own opinion and I'm not speaking for anyone else :) My 2c
Comment 4•8 years ago
|
||
(In reply to Julien G from comment #3) > I personally don't appreciate the sections with only "None" which I feel > useless (no info = nothing to say/display) > > Absence of parameters should be straightforward from the syntaxbox. If one > need to programmatically analyze the content of such pages (you know, > devtools... ;)) this should be pretty easy to deal with. > > Again, that's my own opinion and I'm not speaking for anyone else :) > My 2c That is a very valid point. My only counterargument would be familiarity. Developers use these resources like a dictionary, and if all the pages look exactly the same (as in their structure), it will be easier and quicker for them to find the information they're after. I believe this is the case in particular with constructs like functions, with an anatomy as rigid as "I receive X and return Y" — in my eyes, it would make sense to always clearly identify these components (even if they don't add any new information). In any case, this is a very minor detail. I will carry on working on the "Return value" section as per the guidelines in your replies. Thank you both!
Comment 5•8 years ago
|
||
All the method pages under the Array object now have a "Return value" section. I haven't touched the "Parameters" section, but some of the pages have it despite accepting no parameters (displaying "None"), whilst others simply don't include the section. I would suggest we standardise that one way or the other. The following pages have the section despite having no parameters: - Array.prototype.pop() - Array.prototype.reverse() - Array.prototype.toSource() - Array.prototype.toString() The following pages do not: - Array.prototype.entries() - Array.prototype.keys() - Array.prototype.shift() - Array.prototype.toLocaleString() - Array.prototype.unshift() - Array.prototype.values() - Array.prototype[@@iterator]() - get Array[@@species] Thanks!
Reporter | ||
Comment 6•8 years ago
|
||
(In reply to Eduardo Bouças from comment #5) > All the method pages under the Array object now have a "Return value" > section. Great work! Happy to see this happening. > I haven't touched the "Parameters" section, but some of the pages have it > despite accepting no parameters (displaying "None"), whilst others simply > don't include the section. I would suggest we standardise that one way or > the other. Talked to some more people and also read our guidelines again. I think we should remove the empty "Parameter" section. "If there are no parameters, this section should be omitted." as per https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Write_an_API_reference#Structure_of_a_method_page
Comment 7•8 years ago
|
||
Great! In that case, I'll remove that section as I go along.
Comment 8•8 years ago
|
||
Added "Return value" sections to all pages under: - Typed Array - String - Object - Function properties 160 done, 283 to go! :)
Reporter | ||
Comment 9•8 years ago
|
||
\o/ amazing work, Eduardo!
Comment 10•8 years ago
|
||
I believe this is finished. Here's the list of the 443 method pages I looked through: https://docs.google.com/spreadsheets/d/1RAZ6GklbqoAzwRJcYdIBG31Vyq99GrKn0yD4Vha2Xe4/edit#gid=0 I've asked for an editorial review of a few. I skipped a couple of pages where the method was obsolete or never standardised and I couldn't find official information. I hope this helps! :)
Reporter | ||
Comment 11•8 years ago
|
||
Thanks for all your work Eduardo! I hope you enjoyed contributing to MDN and learned a lot about ECMAScript along your way through all the methods. I enjoyed reading your blog post about your first contribution experience. https://eduardoboucas.com/blog/2016/08/17/mdn.html See you around on #mdn! And yes, this helps! :)
Status: NEW → RESOLVED
Closed: 8 years ago
Resolution: --- → FIXED
You need to log in
before you can comment on or make changes to this bug.
Description
•