-
Notifications
You must be signed in to change notification settings - Fork 22.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
API structure conventions: syntax sections for properties? #4476
Comments
I prefer option 2 as well. It is short and to the point, it clearly demonstrates the read-only status and what the different forms look like (more friendly to beginners that just saying "it's read-only" or whatever and expecting them to know what that entails), and it is in less danger of duplicating parts found in Examples sections. Works for me. |
I'd also opt for option 2, I've written a load of these recently and agree they often end up similar to the examples, or just not very useful. cc: @jpmedley who may have input on this. |
FWIW I think option 0 is best. It looks like option 2 really conveys only one bit of information, which is whether the property is read-only. If so this is a lot of words to say that and it is harder to read, I think, that just "This property is read-only." (which we already say in the page, so it's duplicated in option 2). What would be awesome would be to represent "read-only" as a front matter property of property pages, and render it consistently in the docs. FWIW in stumptown we didn't include "syntax" for property pages: https://github.com/mdn/stumptown-content/blob/master/recipes/javascript-property.yaml |
I am also interested in the type of the object. I like the idea of this stuff being in metadata because then you can more easily run checkers to confirm the needed information is present, and later on decide how to render. Upshot - I lean towards option 0 for syntax, but we need some way to capture this. |
This is very true and maybe there are better ways to represent this clearly. Happy to conclude this with option 0. |
I like option 2, but I'm not fond of using the terms 'getter' and 'setter'.
Those are IDL specific terms. Anyone new to web programming, whether
they're an experienced coder or not, is more likely to know the terms
'read' and 'write'. Option 2 also allows for conveying what the data type
takes or returns (string, number, etc.). I've always tried to give the
setting or returning value a name that conveys what it is.
Joe Medley | Technical Writer, Chrome DevRel | ***@***.*** |
816-678-7195
*If an API's not documented it doesn't exist.*
…On Tue, Apr 27, 2021 at 7:09 AM Florian Scholz ***@***.***> wrote:
It looks like option 2 really conveys only one bit of information, which
is whether the property is read-only.
This is very true and maybe there are better ways to represent this
clearly. Happy to conclude this with option 0.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#4476 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AB6S7C55JGEV7ETHPBQIUQLTK3ARTANCNFSM43SKXBHA>
.
|
Having recently done a bunch of these while working on the Temporal API, I lean toward option 0, especially since just about property in Temporal is read-only. I could live with Option 2. |
Another thing I forgot but that supports option 0: In the JS docs, we actually have a table made especially for properties only. If there is no further input here, I'd like to close and decide for option 0. |
I agree. (though I think a separate issue might be opened to agree properties documentation like in Math/E). A good way to close this might be to open a PR on the user guide with the new process :-) |
I thought we were trying to avoid tables because of the move to markdown.
Also, this is reference material. Option 2 is scannable. Option 0 requires
reading.
Joe Medley | Technical Writer, Chrome DevRel | ***@***.*** |
816-678-7195
*If an API's not documented it doesn't exist.*
…On Thu, Apr 29, 2021 at 7:13 PM Hamish Willee ***@***.***> wrote:
I agree. (though I think a separate issue might be opened to agree
properties documentation like in Math/E).
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#4476 (comment)>, or
unsubscribe
<https://github.com/notifications/unsubscribe-auth/AB6S7C32N5TBRTPZMREMR6DTLIG6HANCNFSM43SKXBHA>
.
|
I propose moving this to the Discussion tracker. |
This came up in #4401 (comment)
@hamishwillee and I are wondering what to with property pages with regards to syntax sections.
It is a bit weird that many property reference pages have a syntax section that try to demonstrate syntax. Unlike methods or constructors, there isn't really a signature or the like to show.
There have been a few strategies that came up and we should standardize a convention (or, there probably is a convention but I'm questioning it).
Option 0
No syntax for properties. There is no syntax section at all.
Option 1
Show how to use a property as a code example (on these pages there are often duplicates in syntax and example sections)
https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize#syntax
or sometimes
Option 2
Explicitly call out getter and setter to be more of a syntax section and less like a code example
https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/origin#syntax
https://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement/hash
Read only:
Read write:
I'm voting for option 2. But I'm open to hear if that's the best way to show how properties' getter and setter behave.
The text was updated successfully, but these errors were encountered: