Skip to main content
Engineering LibreTexts

12.8: Reading Documentation

  • Page ID
    18103
  • \( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

    One of the nice things about Java is that it comes with an extensive library of classes and methods. But before you use them, you might have to read the documentation. And sometimes that’s not easy.

    As an example, let’s look at the documentation for Scanner, which we used in Section 3.2. You can find it by doing a web search for “Java Scanner”. Figure 4.8.1 shows a screenshot of the page.

    Screenshot of the documentation for Scanner.
    Figure \(\PageIndex{1}\): Screenshot of the documentation for Scanner.

    Documentation for other classes uses a similar format. The first line is the package that contains the class, such as java.util. The second line is the name of the class. The “Implemented Interfaces” section lists some of the things a Scanner can do; we won’t say more about that for now.

    The next section of the documentation is a narrative that explains the purpose of the class and includes examples of how to use it. This text can be difficult to read because it uses terms we have not learned yet. But the examples are often very useful. A good way to get started with a new class is to paste the examples into a test file and see if you can compile and run them.

    One of the examples shows how you can use a Scanner to read input from a String instead of System.in:

    String input = "1 fish 2 fish red fish blue fish";
    Scanner s = new Scanner(input);
    

    After the narrative, code examples, and some other details, you will find the following tables:

    Constructor summary:
    Ways of creating, or “constructing”, a Scanner.
    Method summary:
    The list of methods that Scanner provides.
    Constructor detail:
    More information about how to create a Scanner.
    Method detail:
    More information about each method.

    As an example, here is the summary information for nextInt:

    public int nextInt()
    Scans the next token of the input as an int.
    

    The first line is the method’s signature, which specifies the name of the method, its parameters (none), and what type it returns (int). The next line is a short description of what it does.

    The “Method detail” explains more:

    public int nextInt()
    Scans the next token of the input as an int.
    
    An invocation of this method of the form nextInt() behaves in
    exactly the same way as the invocation nextInt(radix),
    where radix is the default radix of this scanner.
    
    Returns:
    the int scanned from the input
    
    Throws: InputMismatchException - if the next token does not match
        the Integer regular expression, or is out of range
    NoSuchElementException - if input is exhausted
    IllegalStateException - if this scanner is closed 

    The “Returns” section describes the result when the method succeeds. In contrast, the “Throws” section describes possible errors and their resulting exceptions. Exceptions are said to be “thrown”, like a referee throwing a flag, or like a toddler throwing a fit.

    It might take you some time to get comfortable reading documentation and learning which parts to ignore. But it’s worth the effort. Knowing what’s available in the library helps you avoid reinventing the wheel. And a little bit of documentation can save you a lot of debugging.


    This page titled 12.8: Reading Documentation is shared under a CC BY-NC-SA 3.0 license and was authored, remixed, and/or curated by Allen B. Downey (Green Tea Press) .

    • Was this article helpful?