Guide to the Information Added by eJavaDoc

The Overview Frame

The overview frame shows the list of packages, with the eJavaDoc icon "  " near each package's name. Click on the icon to see additional information about each package.

The information includes the list of packages that refer to this one (under the title "referenced by"), and the list of packages that this package refers to.

By default, the list is sorted alphabetically. You can change the sort order any time to one based on usage (i.e., by the number of packages that refer to it) by clicking the link at the top of the list. Generally, a package that is referenced by more other packages is a "lower-level" package, providing base functionality, while a package that is referenced by fewer other packages is a "high-level" package, building on the functionality of others.

The icon "" appears near packages that are sealed (more information about package sealing).

The Package Frame

The package frame shows the list of classes and interfaces in a given package (or in the entire component), with the eJavaDoc icon "  " near each type's name. Click on the icon to see additional information about each type.

The information includes the list of classes and interfaces that refer to this one (under the title "referenced by"), and the list of types that this one refers to.

By default, the list is sorted alphabetically. You can change the sort order any time to one based on usage (i.e., by the number of types that refer to it) by clicking the link at the top of the list. Generally, a class or interface that is referenced by more other types is a "lower-level" type, providing base functionality, while a type that is referenced by fewer other types is a "high-level" type, building on the functionality of others.

The icon "" will appear near classes that can be executed (i.e., classes that inclue a public static void main(java.lang.String[]) method). This will enable you to quickly locate program entry points (or, in the case of libraries, sample programs).

The Class Frame

The class frame shows the list of members (fields, methods and constructors) in a class or an interface, with the normal JavaDoc information about each member.

For some of the members, eJavaDoc will add to lines that can be unfolded to reveal additional information. These lines are titled Callgraph information and Effect information; click on the eJavaDoc icon "  " near each line to reveal the additional information.

The following sections detail the type of information you can fine in each of these sections.

Callgraph Information

A callgraph is a data structure containing information about method invocations: which method can potentially invoke which other methods. The Callgraph Information section added by eJavaDoc provides information from this data structure that is relevant to the method (or constructor) at hand: from which methods this method can be invoked, and which methods can be invoked (directly) by this one. These appear under the titles "This method is called by" and "Other methods invoked by this one", respectively.

In the list of methods that could invoke the method at hand, you can see the note "Method overrides (directly or indirectly) a method from outside our scope". This indicates that there could be other sources of invocation for this method, due to polymorphism.

Effect Information

The Effect information section provides information on the way in which the given method interacts with the rest of the component. The provided information is comprised of three parts:

1. How the method parameters and its receiver object (this) are used and/or influenced,
2. The types of values that can be returned from the method, and
3. Static fields that are inspected and/or modified by the method.

It is important to keep in mind that only the operations inside the given method's body are considered, and therefore one should refer to the JavaDoc of invoked methods (whenever available) to understand the full effect of the method's invocation. Besides that, the analysis itself has it own limitations. Please refer to Effect Analysis Limitations below, for more information.

This information is presented in one or more of the following sections:

1. The receiving object (this) - this section provides information about the object on which the given method is invoked (naturally, it appears only for non-static methods). For example, if the invocation statement is "var_a.foo(var_b, 5)", then the receiver object for method foo will be the object referenced by the variable var_a. The receiver object is, in fact, an implicit parameter of the method and therefore the kind of information provided about it is similar in nature to the kind of information provided about the other parameters, as listed in the next section.

2. Information about parameters - this section provides information on each of method's parmaters. The information provided for each of the parameters (including the receiver object) consists of the following items:

   • Passed as an argument to: the list of methods to which the given parameter could be passsed as an argument.

     For example, if the analyzed method includes a statement such as foo(x, this, param3), then the method foo will be listed here for both the receiver object and param3.

   • Invoked methods - [for non-primitive parameters only]: The list of all methods which can be invoked on the given parameter (i.e., for which the given parameter is the receiver object).

     For example, if the "invoked methods" list for the third parameter (named param3) includes the method foo(int, Object) then the analyzed method contains a statement such as var.foo(x, y), where var is a local variable equal to param3. Note that the execution of the statement might be conditional, and therefore this statement will not be executed on every invocation of the analyzed method.

   • Modified fields - [for non-primitive parameters only]: A list of fields of the parameter object that can be modified inside the given method's body. By modification we mean assigning a value to the field.

     For example, a statement such as param2.size = 5 is a modification of the field size of the second parameter.

   • Inspected fields - [for non-primitive parameters only]: A list of fields of the parameter object that can be inspected inside the given method's body.

     For example, if (param1.data == null) is considered an inspection of the field data of the first parameter.

   • Stored in the following fields: A list of all the fields in which the parameter can be stored inside the given method's body.
   • Array elements are inspected - [for array-typed parameters only]: This indicator appears only if the method can read values from the array.
   • Array elements are modified - [for array-typed parameters only]: This indicator appears only if the method can update values in the array.

   Alternatively, the information about a parameter (or the receiver object) could include the indication "This parameter is ignored," meaning that the method simply does not refer to the parameter or use it in any way.

3. Returns one of the following - A list of possible sources for values that could be returned by the method (for non-void methods).

   The values are divided into the following categories. For most of the categories, additional information is available.

   Category	Description	Additional information
   The constant value: v	A constant value. It is either of primitive type, a String, or the null reference.	v - the value itself.
   The receiver object (this)	The value of this.
   The parameter: p	One of the parameters passed to the method.	p - the parameter's name.
   A new object of type: t	An object created inside the method's body.	t - the new object's type.
   A new array of type: a	An array created inside the method's body.	a - the new array's type.
   The result of calling: m	Value returned by a method invoked in the given method's body.	m - the invoked method.
   The instance field: f	Value retrieved from an instance field.	f - the field's name.
   The static field: sf	Value retrieved from a static (class) field	sf - name of the field
   A calculated value	Primitive (numeric) value obtained through arithmetic operations.
   An array element	Value retrieved from some array element
   An exception of type: e	An exception caught by a catch clause.	e - the declared type of the catch clause

4. Modified static fields - the list of static (class) fields whose values could be modified by the given method.

5. Inspected static fields - the list of static fields which could be inspected by the given method.

Effect Information for Fields

Field effect information provides for every field in a Javadoc document the list of all the methods in scope that may inspect (i.e., read) it and the list of those that may modify it. The scope includes every class that was analyzed. Both modification and inspection are detected assuming that all the statements inside every method are executable.

Effect Analysis Limitations

Effect analysis has the following known limitations:

1. The "All Paths Taken" Assumption: All possible conditional execution paths are considered to be actually executable. For example, in the following code fragment:

   	if ((x > 3) && (x < 2)) {
   	   return null;
   	}
   	

   Effect analysis will consider this null value to be a possible return value.

2. Aliasing: The same variable might be reachable through more than a single reference.

   For example, if the value of a parameter p is stored in a field f, and then f is passed to some other method, the effect analysis will not be able to identify this as a passing of the parameter p to the other method.

   To be more precise, effect analysis does handle aliasing when values are stored in the method's local variables, but does not handle aliasing creating using fields, invoked methods, array access and so on.