-
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
Defining page types #15539
Comments
Noting this here so I don't forget it: I noticed you added dictionary as a page type for API. If generally we are getting rid of pages describing dictionaries, we will likely keep some of them. I have been calling them (in my mind only!) interfaces without methods and we are avoiding the term dictionary as they are implemented as JS objects. I think we don't need a separate page type for them and reuse the interface page type. |
Yes, I agree that we will keep some "dictionaries". I'm happy to call them "interfaces without methods". We'll need to find a balance between:
For example if we put dictionaries in the "interface" type, then when we lint, we have to make the "Methods" section in interfaces optional (or let it be empty). That means we have weaker guarantees for interfaces. This might be fine of course, but it's a thing to keep in mind. |
I guess it is because ImageData wants to be a constructible object (it has two constructor forms). Generally, the WebIDL spec https://webidl.spec.whatwg.org might be good to consult when defining page types for APIs. |
Defined page typesIn this comment I'll list all the defined page types as we agree on them. Eventually this list should make its way into some meta-documentation. Generic types
Web/API
|
Is there a discussion somewhere why these aren't folded into web-api-interface and web-api-instance-method? |
Yes, there. |
Tracking issue for openwebdocs/project#91.
In this project we will aim to:
The main aim of this is to define types for structured pages - that is, for pages that are always expected to conform to a particular organization. However, I think it will be helpful to have an explicit "guide" type for pages that aren't structured pages.
Scope
In the first part I'd like to understand the scope of this project. The output of this will be a collection of "doc sets" which we will analyze.
A doc set is a group of related pages on MDN - like the JS docs, or the Learn area, and so on.
I'm doing this in a spreadsheet, here: https://docs.google.com/spreadsheets/d/14RX8EEKPpeYkP2cF5Y_ZKF3JpNJ_24OL7stvZWNJLIY/ .
In the "all doc sets" tab I've listed:
Each of these, more or less, is a doc set.
I've then asked whether each doc set contains structured content. Doc sets that don't contain structured content are out of scope - they're all "guide" pages.
Then for each doc set that contains structured content I've assigned a priority 1-3. I think for now we should consider the P1 sets, which are:
The pages in those doc sets are the pages that we will look at for this project.
I think we should execute the project in two phases:
I think we should do all of the analysis first: that is, we should define page types for all doc sets before we update any pages. That's because it is likely that we will end up changing our mind about some definitions as we analyze later doc sets.
Page type definition
So for the first phase we'll define page types for the following doc sets:
Page type implementation
For the second phase we'll add the defined values to the pages.
The text was updated successfully, but these errors were encountered: