Re: [whatwg/fetch] Add RequestInit members to Request domintro (#620)

annevk commented on this pull request.

The other thing I was wondering is whether we should reference the Request object members or the request concept members. You added informative descriptions to request concept members, but those do not end up being referenced from the domintro boxes now.

> @@ -1001,11 +1001,34 @@ unset.
 "<code>navigate</code>", or "<code>websocket</code>". Unless stated otherwise, it is
 "<code>no-cors</code>".
 
-<p class="note no-backref">Even though the default <a for=/>request</a>
-<a for=request>mode</a> is "<code>no-cors</code>", standards are highly
-discouraged from using it for new features. It is rather unsafe. "<code>navigate</code>" and
-"<code>websocket</code>" are special values for the HTML Standard.
-[[!HTML]]
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>same-origin</code>"
+  <dd>Used to ensure requests are made to same-origin URLs. <a for=/>Fetch</a> will throw an error
+  if the request is not made to a same-origin URL.

`throw an error` -> `return a <a>network error</a>`

> @@ -1001,11 +1001,34 @@ unset.
 "<code>navigate</code>", or "<code>websocket</code>". Unless stated otherwise, it is
 "<code>no-cors</code>".
 
-<p class="note no-backref">Even though the default <a for=/>request</a>
-<a for=request>mode</a> is "<code>no-cors</code>", standards are highly
-discouraged from using it for new features. It is rather unsafe. "<code>navigate</code>" and
-"<code>websocket</code>" are special values for the HTML Standard.
-[[!HTML]]
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>same-origin</code>"
+  <dd>Used to ensure requests are made to same-origin URLs. <a for=/>Fetch</a> will throw an error
+  if the request is not made to a same-origin URL.

This seems like it should be changed throughout.

> @@ -1001,11 +1001,34 @@ unset.
 "<code>navigate</code>", or "<code>websocket</code>". Unless stated otherwise, it is
 "<code>no-cors</code>".
 
-<p class="note no-backref">Even though the default <a for=/>request</a>
-<a for=request>mode</a> is "<code>no-cors</code>", standards are highly
-discouraged from using it for new features. It is rather unsafe. "<code>navigate</code>" and
-"<code>websocket</code>" are special values for the HTML Standard.
-[[!HTML]]
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>same-origin</code>"
+  <dd>Used to ensure requests are made to same-origin URLs. <a for=/>Fetch</a> will throw an error
+  if the request is not made to a same-origin URL.
+
+  <dt>"<code>cors</code>"
+  <dd>Ensures that the request being made is a <a>CORS request</a>. Fetch will throw an error if

I would say "Makes the request a CORS request".

> -"<code>websocket</code>" are special values for the HTML Standard.
-[[!HTML]]
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>same-origin</code>"
+  <dd>Used to ensure requests are made to same-origin URLs. <a for=/>Fetch</a> will throw an error
+  if the request is not made to a same-origin URL.
+
+  <dt>"<code>cors</code>"
+  <dd>Ensures that the request being made is a <a>CORS request</a>. Fetch will throw an error if
+  the requested resource does not understand the <a>CORS protocol</a>.
+
+  <dt>"<code>no-cors</code>"
+  <dd>Restricts requests to using <a>CORS-safelisted methods</a> and
+  <a>CORS-safelisted request-headers</a>. Upon success, fetch will return a
+  <a>opaque filtered response</a>.

an opaque*

> +  <dt>"<code>no-cors</code>"
+  <dd>Restricts requests to using <a>CORS-safelisted methods</a> and
+  <a>CORS-safelisted request-headers</a>. Upon success, fetch will return a
+  <a>opaque filtered response</a>.
+
+  <dt>"<code>navigate</code>"
+  <dd>This is a special mode used only when navigating between documents.
+
+  <dt>"<code>websocket</code>"
+  <dd>This is a special mode used only when establishing a WebSocket connection.
+ </dl>
+
+ <p>Even though the default <a for=/>request</a>
+ <a for=request>mode</a> is "<code>no-cors</code>", standards are highly
+ discouraged from using it for new features. It is rather unsafe. "<code>navigate</code>" and
+ "<code>websocket</code>" are special values for the HTML Standard.

Given that we now mention navigate and websocket above, I don't think we need to mention them here again.

> @@ -1021,14 +1044,27 @@ one or more event listeners are registered on an {{XMLHttpRequestUpload}} object
 which is "<code>omit</code>", "<code>same-origin</code>", or
 "<code>include</code>". Unless stated otherwise, it is "<code>omit</code>".
 
-<p class="note no-backref"><a for=/>Request</a>'s
-<a for=request>credentials mode</a> controls the flow of
-<a for=/>credentials</a> during a <a for=/>fetch</a>. When
-<a for=/>request</a>'s <a for=request>mode</a> is
-"<code>navigate</code>", its
-<a for=request>credentials mode</a> is assumed to be
-"<code>include</code>" and <a for=/>fetch</a> does not currently account
-for other values. If <cite>HTML</cite> changes here, this standard will need corresponding changes.
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>omit</code>"
+  <dd>Used to ensure credentials are not included with this request.

"Excludes credentials from the request". In the sense that it doesn't really ensure it, that's just what happens.

> @@ -1091,6 +1127,20 @@ Unless stated otherwise, it is unset.
 "<code>follow</code>", "<code>error</code>", or "<code>manual</code>".
 Unless stated otherwise, it is "<code>follow</code>".
 
+<div class="note no-backref">
+ <dl>
+  <dt>"<code>follow</code>"
+  <dd>Used to follow all redirects incurred when fetching a resource.
+
+  <dt>"<code>error</code>"
+  <dd>This mode ensures that fetch throws an error when a request for a resource is redirected.

It might make more sense to talk about the response being a redirect. Since no redirect takes place. Same below.

> + via object members of the same name. These are the object members that can be used:</p>
+
+ <dl>
+  <dt>{{RequestInit/method}}
+  <dd>Set to a string to set <var>request</var>'s {{Request/method}}.
+
+  <dt>{{RequestInit/headers}}
+  <dd>Set to a {{Headers}} object or an array of two-item arrays to set <var>request</var>'s
+  {{Request/headers}}.
+
+  <dt>{{RequestInit/body}}
+  <dd>Set to a {{Body}} object or null to set <var>request</var>'s <a>body</a>.
+
+  <dt>{{RequestInit/referrer}}
+  <dd>Set to a string whose value is a same-origin URL, "<code>about:client</code>", or the empty
+  string to set <var>request</var>'s <a>referrer</a>.

comma after empty string?

-- 
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/620#pullrequestreview-84082998