reading-documentation.html


<!doctype html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width,initial-scale=1'>
  <title>Reading Documentation</title>
  <style>
  body {
    font-family: sans-serif;
    line-height: 1.5;
    margin: 40px auto;
    max-width: 640px;
  }
  </style>
</head>
<body>
<h1>Reading Documentation</h1>
<p>
<small>
<a href='/'>This is documentation for reading JavaScript documentation
  generated by documentation.js</a>
</small>
</p>
<p>
How do you read API documentation?
</p>
<p>
Compared to answers, examples, or narrative documentation, API documentation
can be an intimidating read: it's much more like an Encylopedia than a novel.
</p>
<h4>Understanding the types of things</h4>
<p>
API documentation will have a few explicit classes of things that are documented.
Here are some distinctions that aren't always laid out in other kinds
of documentation:
</p>

<ul>
  <li><strong>instance</strong> methods will usually be denoted with the #
    symbol in API documentation. These are methods that you <em>call on an instance of an object</em>.
    For instance, in native JavaScript, strings have a <em>.toUpperCase()</em>
    method. You don't call this method on the String type, but you call it
    on a specific string: like you can write
    <code>var yelling = 'hi'.toUpperCase()</code>
    Remember that, though documentation uses the # character to show what's an
    instance method, you don't actually use that symbol in your source code.
  </li>
  <li><strong>static</strong> methods instead are called on objects or classes
    without needing to instantiate anything. Usually in documentation, static
    methods are denoated with a '.' The <code>fromCharCode</code>
    method of strings is an example of this: it'll be documented as a static
    method and called like <code>String.fromCharCode(20)</code>. Notice
    that we're not calling this on a specific string, but the String
    class itself.
  </li>
</ul>
</body>
</html>