How do you decide which API function documentations to read and how seriously?

Question

Suppose that you are writing or maintaining a piece of code that uses some API that you are not 100% familiar with.

How do you decide whether to read the documentation of a certain call target, and how much time to spend reading it? How do you decide not to read it?

(Let's assume you can read it by opening the HTML documentation, inspecting the source code, or using the hover mechanism in the IDE).

Answer 1

Ideally you should read all of it, but we know that's a pain in the... you know. What I normally do on those cases (and I did that a lot while I worked as a freelancer) is weight some factors and depending on the result, I read the docs.

Factors that tell me I shouldn't read the docs:

• What the function does is easy to guess from the name.
• It isn't relevant to the code I'm maintaining: for example, you are checking how some code deletes files, and you have some function that obviously does some UI update. You don't care about that for now.
• If debugging: the function didn't change the program state in a way meaningful to the task at hand. As before, you don't want to learn what SetOverlayIcon does, if you are debugging the deletion code because it's dying with a file system error.
• The API is just a special case of an API you already know and you can guess what the special case is, and what the special arguments (if any) do. For example, let's say you have WriteToFile(string filename) and WriteToFile(string filename, boolean overwrite).

Of course, everything depends on the context, so even those rules have exceptions.