Documentation
A major element of being a programmer is knowing how to solve issues by looking up how code works in the appropriate documentation. This part will look at how we build documentation, so you then know what it is telling you. We'll then look at some real world documentation so you can see how to use it in solving problems.
Comments in code are there for people who need to understand the detail of how code runs. Documentation is for people who want to use code without understanding how it runs. This seems rather odd – why would people not want to understand how code they are using runs? However, we do it all the time; modern computing wouldn't work if we had to understand all of it. It is a key part of the Object Oriented Programming theory of "encapsulation": not only should code deal with one specific thing well, but in doing so, you shouldn't have to know how it works.
Instead, you should just need to know how to communicate with it, that is, we should know the function names, what to pass into them, what they do, and what they return. The collection of functions we use to interact with something is called its Application Programming Interface. In theory this could also include variables to access directly (especially in Python where they might actually be properties) but generally direct access to variables is frowned upon as we have no idea what's going on inside code with regards variables when we mess with them.
So, for example, we've been been using builtins.print() without knowing anything about how it works. We just know that we pass strings into it, and it prints them on the
screen. This is a perfect bit of OOP API use. The question is, how do we find out how functions work? Here is where we turn to the documentation. API documentation describes (or should) everything
you need to know in order to understand how to use code. APIs and API documentation go so hand-in-hand that you'll often hear things like "did you get that from the API" or "the API doesn't give
much info on that", though many people also refer to the API documentation as "the docs". Here, then, are the
docs for print. Open them up, and you'll see they start with a description of the
arguments/parameters the function takes:
print(*objects, sep=' ', end='\n', file=sys.stdout, flush=False)
Followed by a discussion of each element, and what the function does. If it returned anything, we'd also find a discussion of that.
The neat thing is that we can actually generate such documentation directly from our code, without really knowing about writing webpages. As long as we include the right kind of comments, we can automate their production. To do this, we use a piece of software called a documentation generator.