Fix JavaDoc of AcceptsDelete
From the JavaDoc it is unclear what's the purpose of this interface. Its
class level JavaDoc says that it's to handle DELETE requests on the
RestCollection itself, but its apply method says it's for deleting a
member of the collection and hence for handling DELETE requests on a
member.
The truth is that this interface is used for two cases:
1. handling DELETE requests on the RestCollection (actually this
functionaly seems to be unused, but RestApiServlet supports it)
2. handling DELETE requests on non-existing members of the
RestCollection (in order to create that member)
Generally AcceptsDelete is not supported on root collections (because
support for it is not implemented in RestApiServlet).
Using this interface for two different purposes is a mess and creating
non-existing members of a collection by a DELETE request is strange (but
intended by change Ieeb15d0a91), but since I spent quite some time to
figure out how it works and what it is used for (change edits) I thought
I should at least write my findings into the JavaDoc.
Change-Id: Iaa9559cd775ee51c2b1066ede4107dd9978e4474
Signed-off-by: Edwin Kempin <ekempin@google.com>
diff --git a/java/com/google/gerrit/extensions/restapi/AcceptsDelete.java b/java/com/google/gerrit/extensions/restapi/AcceptsDelete.java
index 6b5da7c..e1c4b3b 100644
--- a/java/com/google/gerrit/extensions/restapi/AcceptsDelete.java
+++ b/java/com/google/gerrit/extensions/restapi/AcceptsDelete.java
@@ -17,17 +17,31 @@
/**
* Optional interface for {@link RestCollection}.
*
- * <p>Collections that implement this interface can accept a {@code DELETE} directly on the
- * collection itself.
+ * <p>This interface is used for 2 purposes:
+ *
+ * <ul>
+ * <li>to support {@code DELETE} directly on the collection itself
+ * <li>to support {@code DELETE} on a non-existing member of the collection (in order to create
+ * that member)
+ * </ul>
+ *
+ * <p>This interface is not supported for root collections.
*/
public interface AcceptsDelete<P extends RestResource> {
/**
- * Handle deletion of a child resource by DELETE on the collection.
+ * Handle
*
- * @param parent parent collection handle.
- * @param id id of the resource being created (optional).
- * @return a view to perform the deletion.
- * @throws RestApiException the view cannot be constructed.
+ * <ul>
+ * <li>{@code DELETE} directly on the collection itself (in this case id is {@code null})
+ * <li>{@code DELETE} on a non-existing member of the collection (in this case id is not {@code
+ * null})
+ * </ul>
+ *
+ * @param parent the collection
+ * @param id id of the non-existing collection member for which the {@code DELETE} request is
+ * done, {@code null} if the {@code DELETE} request is done on the collection itself
+ * @return a view to handle the {@code DELETE} request
+ * @throws RestApiException the view cannot be constructed
*/
RestModifyView<P, ?> delete(P parent, IdString id) throws RestApiException;
}
