From a1797fe924a51716f6c599b05522de21549d745f Mon Sep 17 00:00:00 2001
From: Stefan Majoor <stefan@codeyellow.nl>
Date: Fri, 17 Nov 2023 10:06:43 +0100
Subject: [PATCH] Add documentation for the route decorators

---
 binder/route_decorators.py | 41 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/binder/route_decorators.py b/binder/route_decorators.py
index 3157faab..4e9f5c21 100644
--- a/binder/route_decorators.py
+++ b/binder/route_decorators.py
@@ -1,7 +1,26 @@
+from typing import Optional, List
+
 from .exceptions import BinderMethodNotAllowed, BinderNotFound
 
 
-def _route_decorator(is_detail, name=None, methods=None, extra_route='', unauthenticated=False, *, fetch_obj=False):
+def _route_decorator(
+	is_detail: bool,
+	name: Optional[str] = None,
+	methods: Optional[List[str]] = None,
+	extra_route: str = '',
+	unauthenticated: bool = False,
+	*,
+	fetch_obj: bool = False):
+	"""
+	An abstract decorator, which can be used on a view to automatically register routes on a view
+
+	@param is_detail: True if it is bound to an object (has a pk) false otherwise
+	@param name: The name of the route, i.e. the first part of the URL. E.g. name='foo/', then url = 'api/model/foo/'
+	@param methods: List of http methods that the router should be listed at. E.g. ['GET', 'POST']
+	@param extra_route: Postfix for the url which can be added behind the URL
+	@param unauthenticated: If not True, will first check if the user is logged in.
+	@param fetch_obj: Boolean indicating if we should inject fetch and inject the object
+	"""
 	def decorator(func):
 		def wrapper(self, request=None, *args, **kwargs):
 			if methods is not None and request.method not in methods:
@@ -41,8 +60,28 @@ def wrapper(self, request=None, *args, **kwargs):
 
 
 def list_route(*args, **kwargs):
+	"""
+	Add a list route, i.e. a route without a id in the name
+
+	E.g. on the model foo
+
+		@list_route('bar')
+
+	Will register a route api/foo/bar/
+
+
+	"""
 	return _route_decorator(False, *args, **kwargs)
 
 
 def detail_route(*args, **kwargs):
+	"""
+	Add a list route, i.e. a route with a id in the name
+
+	E.g. on the model foo
+
+		@list_route('bar')
+
+	Will register a route api/foo/1/bar/
+	"""
 	return _route_decorator(True, *args, **kwargs)