Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters?

Question

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 get(self), post(self), 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?

I would say it's completely appropriate and thank you for your efforts, but I'm not a Python guy and the Python community has strong opinions about right & wrong, so I'll refrain from answering. — RubberDuck
– RubberDuck, Commented Feb 7, 2017 at 12:08

Epic Wink · Accepted Answer · 2017-09-01 11:48:07Z

First, here's the PEP on docstring conventions on Python (so 'Gets stuff given some parameters.' goes on the line above and there's a blank line after the docstring :D).

In my mind, the docstring for get should be specifically about get, so if it takes no arguments and returns nothing then there will be no 'Arguments' or 'Returns' section in the docstring. If this is the case, and there are arguments to pass in to MyHandler which affect the function of get, then this information should be put in the class docstring like so:

class MyHandler(tornado.web.RequestHandler):
    '''Handle the internet.

    MyHandler(some_param, other_param).get():
        Get the internet and handle it.

        Args:
            some_param: data about x sent by the client.
            other_param: data about y sent by the client.

    MyHandler().get():
        Get the internet and mishandle it.

    Never mishandle the internet.
    '''

    def get(self):
        '''Gets stuff given some parameters.

        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 = ...

There are also cases where you wouldn't want docstrings: if the parent class already has a sufficient docstring for the get (this doesn't seem to be the case for RequestHandler).

Stack Exchange Network

Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters?

1 Answer 1

Your Answer

Hot Network Questions

Is it appropriate to use docstring `return` and `args` sections to specify HTTP statuses and URL parameters?

1 Answer 1

Your Answer

Sign up or log in

Post as a guest

Related

Hot Network Questions