TS 73 JavaDoc

JavaDoc test specification

Author:Jiri Prox
Version:7.3
Last update:2012/11/07
Introduction: This is test specification for javadoc support in NetBeans. It describes various actions for displaying javadoc, javadoc writing support, javadoc hints and code completion for javadoc

Contents

Test suite: Javadoc in code completion

Purpose: This testsuite is focused on javadoc popup which is shown when code completion window is opened.

  1. Open javadoc window
    1. Put caret in the middle of identifier (e.g. Stri|ng s;)
    2. Press ctrl-space
    3. Put caret in the middle of identifier of class which comes from library with attached sources
    4. Put caret in the middle of identifier of class which comes from library with attached javadoc
    5. Change setting for java platform, which is used by actual project. Set online javadoc, e.g. http://download.oracle.com/javase/6/docs/api/ for jdk 1.6. Call code completion.
    6. Change setting for java platform, which is used by actual project. Set offline javadoc, e.g. for jdk 1.6. Call code completion.
    • EXPECTED RESULT: Code completion is opened, javadoc window for given class is shown. The content is taken from sources or from javadoc, depending on what is available.
  2. Javadoc window navigation
    1. Repeat previous testcase
    2. Click on links in javadoc
    3. Use Back and Forward button in window header
    4. Try button Open Source and Open documentation in external web browser
    • EXPECTED RESULT: The navigation works like in web browser. The Open Source is enabled only when sources for current class are available. When pressed the class is opened in editor. Open documentation opens javadoc page in external web browser if javadoc for actual class is available. Otherwise the button is disabled
  3. Open only javadoc
    1. Repeat previous testcase but use Ctrl-Shift-Space instead of Ctrl-Space
    • EXPECTED RESULT: Only javadoc popup is opened

Test suite: Javadoc Index Search

Purpose:

Setup: Open project which uses library with attached javadoc.

  1. JDK class
    1. Open Javadoc index search (Shift-F1)
    2. Enter String and press enter
    3. Attach javadoc for default platform and repeat previous step
    • EXPECTED RESULT: If javadoc for platform is not attached, the search returns nothing (may return suitable elements from library). Once javadoc is attached, the result contains records for java.lang.String and other elements from JDK
  2. Editor context
    1. Put cursor or some identifier in editor
    2. Press Shift-F1
    • EXPECTED RESULT: Javadoc index search is opened, search for identifier under caret is performed
  3. Navigation
    1. Open index search and perform several queries
    2. Try buttons at right from the query field
    3. Try navigation button in the bottom part of window
    • EXPECTED RESULT: Each button has tooltip and works as expected
  4. External browser
    1. Double click on result item
    • EXPECTED RESULT: Javadoc is opened in external browser

Test suite: Show javadoc actions

Purpose: This suite test various ways how to get javadoc for given element

Setup: Open project using library with attached javadoc

  1. Show javadoc
    1. Put caret on some identifier in editor
    2. Call Show Javadoc action (from popupmenu or Alt-F1)
    • EXPECTED RESULT: Is source is available the javadoc is opened in external web browser, the page is scrolled to shown requested element. (e.g. when called on out on System.out.println() the page for java.lang.System is opened, scrolled to 'out' field)
  2. Show javadoc in navigaton
    1. Open any class
    2. Hover mouse over item in navigator
    3. Press Ctrl-F1
    • EXPECTED RESULT: Javadoc popup is shown when hovering over navigator item. (it's simple popup, no scrolling). When Ctrl-F1 is pressed, javadoc view is opened for actual element
  3. Javadoc view
    1. Open javadoc view
    2. Move cursor to several elements in editor
    • EXPECTED RESULT: Javadoc view show javadoc depending on current position of caret in the editor
  4. Inspect hierarchy/members
    1. Open Inspect hierarchy/members window (Alt-F12, Ctrl-F12)
    2. Browse through dialog
    • EXPECTED RESULT: The javadoc part of dialog always show correct contents
  5. Javadoc reference
    1. Open project which uses library with javadoc
    2. Go to Help -> Javadoc references
    3. Click on some item from submenu
    • EXPECTED RESULT: The javadoc references lists all javadoc sets which are used by opened project. After clicking on some item, the related javadoc is opened in external browser

Test suite: Generating javadoc for project

Setup: Create new project and fill in some javadoc (even for private elements

  1. Create javadoc
    1. From context menu on project select generate javadoc
    • EXPECTED RESULT: javadoc is generated in dist folder. It is opened in browser as well if this option it turned on
  2. Create javadoc - setting
    1. Clean project if javadoc was generated in previous testcase
    2. Open project properties -> Documenting tab
    3. Check all checkboxes
    4. Fill in Window title and Additional Javadoc Options (e.g. -header "Some header" )
    5. Generate javadoc
    6. Try disabling some checkboxes are regenerate javadoc
    • EXPECTED RESULT: The javadoc is generated according the options (clean is needed between javadoc generation)
  3. Create javadoc - warnings
    1. Clean project if javadoc was generated in previous testcase
    2. Make some error in javadoc - e.g. missing argument of @see tag, etc..
    3. Generate javadoc for project
    • EXPECTED RESULT: The output window should contain some warning, clicking of warning open editor and scroll to related position in file

Test suite: Javadoc hints

Purpose: This suite test javadoc hints

Setup: Open any class in editor, turn on javadoc hint in Options -> Java Code -> Hints

  1. Generate javadoc
    1. Put caret on header of public method which does not have javadoc
    2. Use hint
    • EXPECTED RESULT: Javadoc stub is created, it has pre-filled @param, @throws and @return tags, matching the method header
  2. Correct javadoc - add
    1. Add parameter or exception to throws list in method which has correct javadoc
    2. Change return type from void to some type
    3. Use hint to correct javadoc
    • EXPECTED RESULT: Javadoc is updated
  3. Correct javadoc - remove
    1. Remove/rename some parameters, exceptions of change return type in the method header
    2. Apply hints which occurs in javadoc
    • EXPECTED RESULT: The related parts of javadoc is removed
  4. Hints settings
    1. Goto Options -> Java Code -> hints -> javadoc hints
    2. Change scope of both hints
    3. Change Show as value
    • EXPECTED RESULT: Hint are provided according to the selected scope and are show in the way specified by show as combobox

Test suite: Javadoc abbreviation

  1. Generating method javadoc
    1. Put cater before method w/o javadoc (using generics)
    2. Type "/**" and press enter
    • EXPECTED RESULT: Javadoc stub is created, it contains all parameters, exceptions from throws clause and @return tag if it's non-void method.
  2. Class javadoc
    1. Put caret before class wih generics
    2. Type "/**" and press enter
    • EXPECTED RESULT: Javadoc containing @author and @param tags is generated
  3. Negative testcase
    1. try use /** in inappropriate position (at the end of file, before other javadoc, inside method etc...)
    • EXPECTED RESULT: Empty stub is created

Test suite: Javadoc completion

Purpose: This suite is focused on completion in javadoc

  1. Param tag
    1. Put cursor inside empty javadoc for method public <T> T method(T i1, X i2) throws FileNotFoundException {
    2. Type @ and invoke javadoc completion if it isn't opened automatically
    3. select "param"
    4. invoke javadoc completion
    • EXPECTED RESULT: The completion in step 2 provides all suitable tags (deprecated, exception, param, return, see, serialData, since, throws ). In step 4 all params are provided (i1,i2, <T>)
  2. Param tag for class
    1. Put cursor inside empty javadoc for class public class Test<X>{
    2. Type @ and invoke javadoc completion if it isn't opened automatically
    3. select "param"
    4. invoke javadoc completion
    • EXPECTED RESULT: In step 2 following tags are provided: author, deprecated, param, see, serial, since, version. In step 4 the <X> parameter is provided
  3. Throws tag
    1. Put cursor inside empty javadoc for method public <T> T method(T i1, X i2) throws FileNotFoundException {
    2. Type @ and invoke javadoc completion if it isn't opened automatically
    3. select "throws"/"exception"
    4. invoke javadoc completion
    • EXPECTED RESULT: All subclass of Exception are listed. The class present in throws clause are at the beginning of the list
  4. {@ tags
    1. Put cursor inside empty javadoc for method,class or field
    2. Type {@ and invoke javadoc completion if it isn't opened automatically
    • EXPECTED RESULT: The following tags are provided: code, docRoot, link, linkPlain, literal. In addition it it there is also tag inheritDoc for methods and tag value for fields. The {@link and {@linkPlain tags behaves like @see

Test suite: Javadoc - javasource features

Purpose: This suite describes features from java source module which were extendet to work in javadoc

Setup: Open any class in editor,

  1. Add import
    1. In javadoc type "@see List"
    2. Call Fix Imports (ctrl-shift-I)
    • EXPECTED RESULT: Fix import dialog is opened, providing list of all classes named List in classpath. After confirm the correct class is imported.
  2. Add import 2
    1. Remove import of List added in previous testcase
    2. Put caret over List in javadoc
    3. Call Fast Fix Import (alt-shift-I)
    • EXPECTED RESULT: Fast Fix import dialog is opened, providing list of all classes named List in classpath. After confirm the correct class is imported.
  3. Unused import
    1. Add import for java.io.File
    2. Add {@link File} to the javadoc
    • EXPECTED RESULT: At first import is marked as unused, after adding the link tag, the import is not marked as unused any more
  4. Resolve symbol
    1. Remove import for File from previous testcase
    2. Write {@link File# in javadoc
    3. Invoke code completion (ctrl-space)
    4. Impot java.io.File
    5. invoke code completion (ctrl-space) behind {@link File#
    6. Add @see or {@link or {@linkPlain and name of some class
    7. Import the class if it isn't already imported
    8. Put caret over class identifier
    • EXPECTED RESULT: Mark Occurrences works - all occurrences of class under cursor are highlighted
  5. Rename class
    1. Create class Klass in package anotherPack
    2. In current file put somewhere in javadoc following text: @see Klass
    3. Add necessary import
    4. Rename class Klass to different name (check rename in comments)
    • EXPECTED RESULT: @see tag is updated to reflect actual name
  6. Ctrl-navigation
    1. Ctrl-click on class name or method in @see, {@link or {@linkPlain tag
    • EXPECTED RESULT: The source file is opened if available

Test suite: Analyze Javadoc

Comments: Open attached project TS_73_JavaDoc.zip. The Analyze javadoc action can be found in project view context menu Tools -> Analyze javadoc

  1. Analyze scope
    1. Select following elements in the project view
      1. whole source root
      2. package
      3. single file
    2. Call Analyze javadoc for each element
    • EXPECTED RESULT: The source files related to selected element are analyzed. And new window 'Analyzer' is opened, showing problems in javadoc.
  2. Browsing Javadoc errors
    1. Select source root
    2. Call Analyze Javadoc
    3. In Analyzer window press up/down button
    • EXPECTED RESULT: The highlighted line in Analyzer is moved to next/previous error. The cursor is moved to related element in editor. (File is opened if necessary)
  3. Fixing errors
    1. Analyze javadoc for some file.
    2. In Analyzer check 'Fix on next'
    3. Press Next button (down arrow)
    • EXPECTED RESULT: The highlighted line is moved to new error, the line is striked through and the javadoc is corrected, cursor it moved to editor to edit javadoc manually
  4. Go over fixed errors
    1. Analyze javadoc for some file.
    2. Fix several problems
    3. Uncheck 'fix on next' and check 'Go over fixed problems'
    4. Press Next/Previous button
    • EXPECTED RESULT: The highlighted line moves only over fixed errors
  5. Fix selected errors
    1. Analyze javadoc for some file.
    2. Check several checkboxes
    3. Press 'Fix selected'
    • EXPECTED RESULT: The fix selected button is enabled when any checkbox is seleced. After pressing the button the selected errors are fixed, the related lines in Analyzer window are crossed
  6. Reload
    1. Analyze javadoc for some file.
    2. Check several checkboxes
    3. Press reload button
    • EXPECTED RESULT: The javadoc is analyzed again. The Analyzer window is updated

Test suite: Colors

  1. Javadoc Colors
    1. Open javadoc.Coloring
    2. Check the color of javadoc, first sentence of javadoc, html tag, javadoc tag, parameter name etc...
    • EXPECTED RESULT:Image:TS_73_JavaDocColoring.png
Not logged in. Log in, Register

By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo