Re: [whatwg/fetch] [WIP] Request domintro box (#617)

annevk commented on this pull request.

This looks really great. Thanks! I have a bunch of nits and one somewhat larger comment about describing the dictionary, but if you don't feel like it I don't think it's necessary for this to land. Just something that would be good to get to eventually.

> @@ -4855,6 +4855,70 @@ initially a new {{AbortSignal}} object.
 <a for=Request>request</a>'s
 <a for=request>body</a>.
 
+<dl class=domintro>
+ <dt><code><var>request</var> = new <a constructor lt="Request()">Request</a>(<var>input</var> [,
+ <var>init</var>])</code>
+ <dd>Returns a new <var>request</var> whose <a attribute for=Request>url</a> attribute value is
+ <var>input</var> if <var>input</var> is a string, and <var>input</var>'s
+ <a attribute for=Request>url</a> if <var>input</var> is a {{Request}}. The optional

a {{Request}} object

> @@ -4855,6 +4855,70 @@ initially a new {{AbortSignal}} object.
 <a for=Request>request</a>'s
 <a for=request>body</a>.
 
+<dl class=domintro>
+ <dt><code><var>request</var> = new <a constructor lt="Request()">Request</a>(<var>input</var> [,
+ <var>init</var>])</code>
+ <dd>Returns a new <var>request</var> whose <a attribute for=Request>url</a> attribute value is
+ <var>input</var> if <var>input</var> is a string, and <var>input</var>'s
+ <a attribute for=Request>url</a> if <var>input</var> is a {{Request}}. The optional
+ <var>init</var> argument allows for setting attributes appearing in {{RequestInit}} via object
+ members of the same name.

Describing the dictionary members here seems like a good idea. I think we typically do that. See the observe() method at https://dom.spec.whatwg.org/#interface-mutationobserver for instance.

> + <dt><code><var>request</var> = new <a constructor lt="Request()">Request</a>(<var>input</var> [,
+ <var>init</var>])</code>
+ <dd>Returns a new <var>request</var> whose <a attribute for=Request>url</a> attribute value is
+ <var>input</var> if <var>input</var> is a string, and <var>input</var>'s
+ <a attribute for=Request>url</a> if <var>input</var> is a {{Request}}. The optional
+ <var>init</var> argument allows for setting attributes appearing in {{RequestInit}} via object
+ members of the same name.
+
+ <dt><code><var>request</var> . <a attribute for=Request>method</a></code>
+ <dd>Returns <var>request</var>'s HTTP method, which is "<code>GET</code>" by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>url</a></code>
+ <dd>Returns the URL of <var>request</var> as a string.
+
+ <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.

We should maybe indicate here that this does not include headers typically added in the "network layer", such as `Host`. See also https://fetch.spec.whatwg.org/#http-header-layer-division.

> + <var>input</var> if <var>input</var> is a string, and <var>input</var>'s
+ <a attribute for=Request>url</a> if <var>input</var> is a {{Request}}. The optional
+ <var>init</var> argument allows for setting attributes appearing in {{RequestInit}} via object
+ members of the same name.
+
+ <dt><code><var>request</var> . <a attribute for=Request>method</a></code>
+ <dd>Returns <var>request</var>'s HTTP method, which is "<code>GET</code>" by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>url</a></code>
+ <dd>Returns the URL of <var>request</var> as a string.
+
+ <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.
+
+ <dt><code><var>request</var> . <a attribute for=Request>destination</a></code>
+ <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",

Comma  after e.g. too.

> + <var>input</var> if <var>input</var> is a string, and <var>input</var>'s
+ <a attribute for=Request>url</a> if <var>input</var> is a {{Request}}. The optional
+ <var>init</var> argument allows for setting attributes appearing in {{RequestInit}} via object
+ members of the same name.
+
+ <dt><code><var>request</var> . <a attribute for=Request>method</a></code>
+ <dd>Returns <var>request</var>'s HTTP method, which is "<code>GET</code>" by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>url</a></code>
+ <dd>Returns the URL of <var>request</var> as a string.
+
+ <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.
+
+ <dt><code><var>request</var> . <a attribute for=Request>destination</a></code>
+ <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",

But no comma between document and or.

> +
+ <dt><code><var>request</var> . <a attribute for=Request>method</a></code>
+ <dd>Returns <var>request</var>'s HTTP method, which is "<code>GET</code>" by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>url</a></code>
+ <dd>Returns the URL of <var>request</var> as a string.
+
+ <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.
+
+ <dt><code><var>request</var> . <a attribute for=Request>destination</a></code>
+ <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",
+ or "<code>script</code>".
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrer</a></code>
+ <dd>Returns the referrer of <var>request</var>. Its value can be a same origin URL if explicitly

same-origin*

> + <dd>Returns <var>request</var>'s HTTP method, which is "<code>GET</code>" by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>url</a></code>
+ <dd>Returns the URL of <var>request</var> as a string.
+
+ <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.
+
+ <dt><code><var>request</var> . <a attribute for=Request>destination</a></code>
+ <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",
+ or "<code>script</code>".
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrer</a></code>
+ <dd>Returns the referrer of <var>request</var>. Its value can be a same origin URL if explicitly
+ set in <var>init</var>, the empty string to indicate no referrer, and "<code>about:client</code>"
+ when defaulting to the document's <a for=Document>URL</a>. This is used during fetching to

This isn't really accurate for when you'd use fetch() in workers. I wonder how specific we want to get. I think I'd be okay with "the global's default" or some such.

> + <dt><code><var>request</var> . <a attribute for=Request>headers</a></code>
+ <dd>Returns a {{Headers}} object consisting of the headers associated with <var>request</var>.
+
+ <dt><code><var>request</var> . <a attribute for=Request>destination</a></code>
+ <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",
+ or "<code>script</code>".
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrer</a></code>
+ <dd>Returns the referrer of <var>request</var>. Its value can be a same origin URL if explicitly
+ set in <var>init</var>, the empty string to indicate no referrer, and "<code>about:client</code>"
+ when defaulting to the document's <a for=Document>URL</a>. This is used during fetching to
+ determine the value of the "<code>Referer</code>" header of the request being made.
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrerPolicy</a></code>
+ <dd>Returns the referrer policy associated with <var>request</var>. This is used during
+ fetching to compute the value of of the <var>request</var>'s referrer.

of of -> of

> + <dd>Returns the kind of resource requested by <var>request</var>, e.g. "<code>document</code>",
+ or "<code>script</code>".
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrer</a></code>
+ <dd>Returns the referrer of <var>request</var>. Its value can be a same origin URL if explicitly
+ set in <var>init</var>, the empty string to indicate no referrer, and "<code>about:client</code>"
+ when defaulting to the document's <a for=Document>URL</a>. This is used during fetching to
+ determine the value of the "<code>Referer</code>" header of the request being made.
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrerPolicy</a></code>
+ <dd>Returns the referrer policy associated with <var>request</var>. This is used during
+ fetching to compute the value of of the <var>request</var>'s referrer.
+
+ <dt><code><var>request</var> . <a attribute for=Request>mode</a></code>
+ <dd>Returns the mode associated with <var>request</var>, which is a string indicating whether
+ or not the request should use CORS, or will only be sent to a same origin URL.

should -> will
will be restricted to same-origin URLs*

> + set in <var>init</var>, the empty string to indicate no referrer, and "<code>about:client</code>"
+ when defaulting to the document's <a for=Document>URL</a>. This is used during fetching to
+ determine the value of the "<code>Referer</code>" header of the request being made.
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrerPolicy</a></code>
+ <dd>Returns the referrer policy associated with <var>request</var>. This is used during
+ fetching to compute the value of of the <var>request</var>'s referrer.
+
+ <dt><code><var>request</var> . <a attribute for=Request>mode</a></code>
+ <dd>Returns the mode associated with <var>request</var>, which is a string indicating whether
+ or not the request should use CORS, or will only be sent to a same origin URL.
+
+ <dt><code><var>request</var> . <a attribute for=Request>credentials</a></code>
+ <dd>Returns the credentials mode associated with <var>request</var>, which is a string
+ indicating whether or not credentials should be sent with the request always, never, or only when
+ sent to a same origin URL.

same-origin*

> + <dd>Returns the referrer of <var>request</var>. Its value can be a same origin URL if explicitly
+ set in <var>init</var>, the empty string to indicate no referrer, and "<code>about:client</code>"
+ when defaulting to the document's <a for=Document>URL</a>. This is used during fetching to
+ determine the value of the "<code>Referer</code>" header of the request being made.
+
+ <dt><code><var>request</var> . <a attribute for=Request>referrerPolicy</a></code>
+ <dd>Returns the referrer policy associated with <var>request</var>. This is used during
+ fetching to compute the value of of the <var>request</var>'s referrer.
+
+ <dt><code><var>request</var> . <a attribute for=Request>mode</a></code>
+ <dd>Returns the mode associated with <var>request</var>, which is a string indicating whether
+ or not the request should use CORS, or will only be sent to a same origin URL.
+
+ <dt><code><var>request</var> . <a attribute for=Request>credentials</a></code>
+ <dd>Returns the credentials mode associated with <var>request</var>, which is a string
+ indicating whether or not credentials should be sent with the request always, never, or only when

should -> will

> +
+ <dt><code><var>request</var> . <a attribute for=Request>cache</a></code>
+ <dd>Returns the cache mode associated with <var>request</var>, which is a string indicating
+ how the the request will interact with the browser's cache when fetching.
+
+ <dt><code><var>request</var> . <a attribute for=Request>redirect</a></code>
+ <dd>Returns the redirect mode associated with <var>request</var>, which is a string indicating
+ how redirects for the request will be handled during fetching. A <a>request</a> will follow
+ redirects by default.
+
+ <dt><code><var>request</var> . <a attribute for=Request>integrity</a></code>
+ <dd>Returns <var>request</var>'s subresource integrity, which is a cryptographic hash of the
+ resource being fetched. Its value may consist of multiple hashes separated by whitespace.
+
+ <dt><code><var>request</var> . <a attribute for=Request>keepalive</a></code>
+ <dd>Returns a boolean indicating whether or not <var>request</var> can outlive the page it was

the global

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/617#pullrequestreview-69510155