I'm working on a web application project which uses Tornado as the web frontend. Currently, I'm in the process of writing up docs and adding docstrings to the code base with Pydoc.
As a web API framework, Tornado applications are structured with each API endpoint having a handler class, and with each handler class having a separate Python method for each HTTP request method that endpoint should handle. These Python methods always have a signature of the form
put(self), etc., and don't take any arguments themselves.
Instinctively, I want to use Pydoc like this:
class MyHandler(tornado.web.RequestHandler): def get(self): ''' Gets stuff given some parameters. Args: some_param: data about x sent by the client. other_param: data about y sent by the client. Returns: HTTP 200 if everything's OK. HTTP 404 if other_param can't be found. HTTP 500 if some_param results in a database error. ''' x = self.get_argument('some_param') y = self.get_argument('other_param') # ...
... But I'm not sure that this is common (or best) practice, since I'm documenting URL parameters and HTTP status codes as though they were formal parameters and return values for a function which has neither.
Is this an acceptable, or common, use of docstrings in web apps? If not, what's the correct way of documenting handlers and their methods?