add doc and todos

hapic/context.py

@@ -30,6 +30,7 @@ class ContextInterface(object):
 
     def get_response(
         self,
+        # TODO BS 20171228: rename into response_content
         response: dict,
         http_code: int,
     ) -> typing.Any:
@@ -48,18 +49,21 @@ class ContextInterface(object):
     ) -> RouteRepresentation:
         raise NotImplementedError()
 
+    # TODO BS 20171228: rename into openapi !
     def get_swagger_path(self, contextualised_rule: str) -> str:
         """
         Return OpenAPI path with context path
+        TODO BS 20171228: Give example
         :param contextualised_rule: path of original context
         :return: OpenAPI path
         """
         raise NotImplementedError()
 
+    # TODO BS 20171228: rename into "bypass"
     def by_pass_output_wrapping(self, response: typing.Any) -> bool:
         """
-        Return True if the controller response is in final state: we do not
-        have to apply output wrapper on it.
+        Return True if the controller response is the final response object:
+        we do not have to apply any processing on it.
         :param response: the original response of controller
         :return:
         """

hapic/decorator.py

@@ -377,6 +377,11 @@ class InputFilesControllerWrapper(InputControllerWrapper):
 
 
 class ExceptionHandlerControllerWrapper(ControllerWrapper):
+    """
+    This wrapper is used to wrap a controller and catch given exception if
+    raised. An error will be generated in collaboration with context and
+    returned.
+    """
     def __init__(
         self,
         handled_exception_class: typing.Type[Exception],

hapic/doc.py

@@ -111,6 +111,16 @@ class DocGenerator(object):
         title: str='',
         description: str='',
     ) -> dict:
+        """
+        Generate an OpenApi 2.0 documentation. Th given context will be used
+        to found controllers matching with given DecoratedController.
+        :param controllers: List of DecoratedController to match with context
+        controllers
+        :param context: a context instance
+        :param title: The generated doc title
+        :param description: The generated doc description
+        :return: a apispec documentation dict
+        """
         spec = APISpec(
             title=title,
             info=dict(description=description),

hapic/hapic.py

@@ -87,6 +87,21 @@ class Hapic(object):
         self._context = None
 
     def with_api_doc(self, tags: typing.List['str']=None):
+        """
+        Permit to generate doc about a controller. Use as a decorator:
+
+        ```
+        @hapic.with_api_doc()
+        def my_controller(self):
+            # ...
+        ```
+
+        What it do: Register this controller with all previous given
+        information like `@hapic.input_path(...)` etc.
+
+        :param tags: list of string tags (OpenApi)
+        :return: The decorator
+        """
         # FIXME BS 20171228: Documenter sur ce que ça fait vraiment (tester:
         # on peut l'enlever si on veut pas generer la doc ?)
         tags = tags or []  # FDV
@@ -350,9 +365,16 @@ class Hapic(object):
             return decoration.get_wrapper(func)
         return decorator
 
-    def generate_doc(self, title: str='', description: str=''):
+    def generate_doc(self, title: str='', description: str='') -> dict:
+        """
+        See hapic.doc.DocGenerator#get_doc docstring
+        :param title: Title of generated doc
+        :param description: Description of generated doc
+        :return: dict containing apispec doc
+        """
         return self.doc_generator.get_doc(
             self._controllers,
             self.context,
             title=title,
-            description=description)
+            description=description,
+        )

tests/func/test_doc.py

@@ -10,6 +10,7 @@ from tests.base import MyContext
 class TestDocGeneration(Base):
     def test_func__input_files_doc__ok__one_file(self):
         hapic = Hapic()
+        # TODO BS 20171113: Make this test non-bottle
         app = bottle.Bottle()
         hapic.set_context(MyContext(app=app))
 
@@ -39,6 +40,7 @@ class TestDocGeneration(Base):
 
     def test_func__input_files_doc__ok__two_file(self):
         hapic = Hapic()
+        # TODO BS 20171113: Make this test non-bottle
         app = bottle.Bottle()
         hapic.set_context(MyContext(app=app))
 
@@ -75,6 +77,7 @@ class TestDocGeneration(Base):
 
     def test_func__output_file_doc__ok__nominal_case(self):
         hapic = Hapic()
+        # TODO BS 20171113: Make this test non-bottle
         app = bottle.Bottle()
         hapic.set_context(MyContext(app=app))
 
@@ -94,6 +97,7 @@ class TestDocGeneration(Base):
 
     def test_func__input_files_doc__ok__one_file_and_text(self):
         hapic = Hapic()
+        # TODO BS 20171113: Make this test non-bottle
         app = bottle.Bottle()
         hapic.set_context(MyContext(app=app))
 

tests/func/test_marshmallow_decoration.py

@@ -24,7 +24,6 @@ class TestMarshmallowDecoration(Base):
         class MySchema(marshmallow.Schema):
             file_abc = marshmallow.fields.Raw(required=True)
 
-        @hapic.with_api_doc()
         @hapic.input_files(MySchema())
         def my_controller(hapic_data=None):
             assert hapic_data
@@ -46,7 +45,6 @@ class TestMarshmallowDecoration(Base):
         class MySchema(marshmallow.Schema):
             file_abc = marshmallow.fields.Raw(required=True)
 
-        @hapic.with_api_doc()
         @hapic.input_files(MySchema())
         def my_controller(hapic_data=None):
             assert hapic_data
@@ -72,7 +70,6 @@ class TestMarshmallowDecoration(Base):
         class MySchema(marshmallow.Schema):
             file_abc = marshmallow.fields.Raw(required=True)
 
-        @hapic.with_api_doc()
         @hapic.input_files(MySchema())
         def my_controller(hapic_data=None):
             assert hapic_data