From aabac3f2d755e85aad4be743a36cbfcc19862255 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Martin=20Bj=C3=B6rklund?= <mbj4668@gmail.com>
Date: Wed, 7 Oct 2020 13:50:03 +0200
Subject: [PATCH] updated documentation on AcceptCallback and removed test case
 for deprecated return value

---
 doc/src/manual/cowboy_rest.asciidoc | 12 +++++++++---
 test/handlers/create_resource_h.erl |  4 +---
 test/rest_handler_SUITE.erl         | 11 -----------
 3 files changed, 10 insertions(+), 17 deletions(-)

diff --git a/doc/src/manual/cowboy_rest.asciidoc b/doc/src/manual/cowboy_rest.asciidoc
index 3583c116..e091bc25 100644
--- a/doc/src/manual/cowboy_rest.asciidoc
+++ b/doc/src/manual/cowboy_rest.asciidoc
@@ -89,7 +89,6 @@ AcceptCallback(Req, State) -> {Result, Req, State}
 Result  :: true
          | {created, URI :: iodata()}
          | {see_other, URI :: iodata()}
-         | {true, URI :: iodata()}
          | false
 Default  - crash
 ----
@@ -105,8 +104,12 @@ that is being created or replaced.
 For POST requests, the body is typically application-specific
 instructions on how to process the request, but it may also be a
 representation of the resource. When creating a new resource with POST
-at a different location, return `{create, URI}` or `{see_other, URI`}
-with `URI` the new location. The return value `{true, URI}` is deprecated.
+at a different location, return `{created, URI}` or `{see_other, URI`}
+with `URI` the new location.
+
+Returning `{created, URI`} will result in a '201 Created' response.
+
+Returning `{see_other, URI`} will result in a '303 See Other' response.
 
 For PATCH requests, the body is a series of instructions on
 how to update the resource. Patch files or JSON Patch are
@@ -728,6 +731,9 @@ listed here, like the authorization header.
 
 == Changelog
 
+* *2.9*: An `AcceptCallback` can now return `{created, URI}` and
+         `{see_other, URI}`.  The old return value `{true, URI}` is
+         deprecated.
 * *2.7*: The media type wildcard in `content_types_accepted`
          is now documented.
 * *2.6*: The callback `rate_limited` was added.
diff --git a/test/handlers/create_resource_h.erl b/test/handlers/create_resource_h.erl
index 89ee787e..f82e610e 100644
--- a/test/handlers/create_resource_h.erl
+++ b/test/handlers/create_resource_h.erl
@@ -24,7 +24,5 @@ from_text(Req=#{qs := Qs}, State) ->
 		<<"created">> ->
 			{{created, NewURI}, Req, State};
 		<<"see_other">> ->
-			{{see_other, NewURI}, Req, State};
-		_ ->
-			{{true, NewURI}, Req, State}
+			{{see_other, NewURI}, Req, State}
 	end.
diff --git a/test/rest_handler_SUITE.erl b/test/rest_handler_SUITE.erl
index 10f5948b..8b2b4447 100644
--- a/test/rest_handler_SUITE.erl
+++ b/test/rest_handler_SUITE.erl
@@ -497,17 +497,6 @@ create_resource_see_other(Config) ->
 	{response, _, 303, _} = gun:await(ConnPid, Ref),
 	ok.
 
-create_resource_legacy(Config) ->
-	doc("POST to an existing resource to create a new resource. "
-		"When the accept callback returns {true, NewURI}, the legacy "
-		"behavior is a 302 See Other reply."),
-	ConnPid = gun_open(Config),
-	Ref = gun:post(ConnPid, "/create_resource", [
-		{<<"content-type">>, <<"application/text">>}
-	], <<"hello">>, #{}),
-	{response, _, 303, _} = gun:await(ConnPid, Ref),
-	ok.
-
 error_on_malformed_accept(Config) ->
 	doc("A malformed Accept header must result in a 400 response."),
 	do_error_on_malformed_header(Config, <<"accept">>).