4.7. FAQ

  1. What is the difference between throw, throws, and @throws?

    • The throw keyword is used in a block of code to explicitly throw an exception. This is desirable when you want your method to throw an exception under some predefined conditions. If the exception object being thrown using throw is a checked exception, then you might also need to include throws in the method signature.

    • The throws keyword is used in a method or constructor signature to list the checked exceptions that the method is allowed to propagate.

    • The @throws tag is a Javadoc tag that is used in the Javadoc comment associated with a method (or constructor) to document that it can throw an exception under certain circumstances. The rule of thumb is this: if your method throws an exception (checked or unchecked) that a user of your method should handle, then you should document that exception using @throws in the associated Javadoc comment.

  1. How do I update the documentation website?

    To update the documentation website, rerun the same javadoc command you used to originally generate the website from the same directory. You should not need to recreate the symbolic link.

    More details found here under “Updating the Website”.

  2. Why not tell javadoc to generate the API documentation website directly in ~/public_html/cs1302-javadoc-doc instead of doc ?

    That is definitely an option, assuming the ~/public_html/cs1302-javadoc-doc directory already exists. We chose the symbolic link approach in the tutorial because it helps keep the javadoc command nice and short and to provide an example of a symbolic link.

  3. Why not use cp or mv to copy or move (respectively) the generated API documentation website directly to ~/public_html/cs1302-javadoc-doc instead using ln ?

    Since our use of ln created a symbolic link to the doc directory, we can now regenerate the API documentation website in doc and have those changes be automatically reflected in ~/public_html/cs1302-javadoc-doc. Also, from an organizational standpoint, it makes sense to have the documentation contained within the main project directory.