Improving API Documentation Usability with Knowledge Pushing - Revision history

Skalogryz: /* Threats to validity */

2019-05-16T18:01:58Z

‎Threats to validity

Skalogryz: /* Third debugging task */

2019-05-16T17:59:31Z

‎Third debugging task

Show changes

Skalogryz: /* Subjects and procedures */

2019-05-16T17:54:28Z

‎Subjects and procedures

Skalogryz: /* Study design */

2019-05-16T15:12:06Z

‎Study design

Skalogryz: /* Knowledge space */

2019-05-16T15:04:26Z

‎Knowledge space

Skalogryz: /* The eMoose tool */

2019-05-16T15:00:56Z

‎The eMoose tool

Skalogryz: /* Directives */

2019-05-16T14:57:54Z

‎Directives

Skalogryz: /* Contributions and importance */

2019-05-16T14:56:55Z

‎Contributions and importance

Skalogryz: /* Abstract */

2019-05-16T14:50:02Z

‎Abstract

Skalogryz at 14:49, 16 May 2019

2019-05-16T14:49:52Z

@@ Line 811: / Line 811: @@
 addition, few developers are versed in all the intricacies of
 familiar APIs, such as <code>Swing</code>.
 [[Category:Article]]

@@ Line 476: / Line 476: @@
 and an experimental condition (EXP) in which eMoose is
 activated and decorations are presented based on our corpus of annotated APIS. All subjects were also given a web
-browser with the HTML JavaDocs of all relevant APIS.
+browser with the HTML JavaDocs of all relevant APIs.
 [[Category:Article]]

← Older revision		Revision as of 15:12, 16 May 2019
Line 445:		Line 445:

	==Study design==		==Study design==
		+	Our discussion so far presented the notion of directives
		+	and our technique for “pushing” them. However, there is
		+	currently limited evidence for the severity of the directive
		+	awareness problem with standard tools, and it is not clear
		+	whether our technique is effective or distracting. Clearly,
		+	these issues largely depend on the specific individual and
		+	context during actual use. Nevertheless, we chose to also
		+	investigate them via a comparative lab study.
		+
		+	===Subjects and procedures===
		+	Subjects were recruited from our university campus with
		+	ads that promised a fixed compensation and also raffle tickets for each completed task as a motivation to perform well.
		+	Applicants were required to be at least seniors in CS or related fields, with experience in JAVA and Eclipse, and at
		+	least one internship. A total of 26 applicants met these requirements. Due to the to the limitations of the academic
		+	environment, however, 24 of them were male, and most
		+	were students in a professional masters program who were
		+	relative novices. Two other subjects were seniors with significant experience, and three were Ph.D. candidates.
		+
		+	At the beginning of the session, subjects had to fill a
		+	background questionnaire and pass a short skills test. We
		+	we also verified that they ''were not familiar'' with the APIS
		+	used in the study. They signed consent to screen- and
		+	audio- recording, and then received a 10 minute tutorial
		+	covering the concept of directives, and the purpose and use
		+	of eMoose, including situations of polymorphism and conformance violations. They performed five tasks, and then
		+	completed a detailed survey.
		+
		+	For every task we defined a control condition (CTL) to
		+	be one in which the standard distribution of Eclipse is used,
		+	and an experimental condition (EXP) in which eMoose is
		+	activated and decorations are presented based on our corpus of annotated APIS. All subjects were also given a web
		+	browser with the HTML JavaDocs of all relevant APIS.

	[[Category:Article]]		[[Category:Article]]

@@ Line 330: / Line 330: @@
 added in the method’s documentation block and replace or
 mirror directives in the text
 [[Category:Article]]

← Older revision		Revision as of 15:00, 16 May 2019
Line 301:		Line 301:

	==The ''eMoose'' tool==		==The ''eMoose'' tool==
		+	The functionality described in this paper is only part
		+	of our ''eMoose'' (Abbreviation for External Memory Of Open Source Efforts.)
		+	framework, which is designed to serve
		+	as a comprehensive memory aid for software engineers
		+	that manages both artifact-centric and temporal information. Since this paper is concerned only with artifact-centric
		+	information, we shall use the term eMoose solely for the
		+	functionality for tagging and pushing knowledge supported
		+	by the publicly-available client-side version of the tool [2].
		+
		+	===Knowledge space===
		+	Every instance of the eMoose client plug-in manages
		+	an abstract knowledge space which consists of knowledge
		+	items (KIs). A KI is an atomic and concise element which is
		+	intended to be captured rapidly and cost-effectively as a single sentence or text line conveying one idea. In the scope of
		+	this paper, every KI corresponds to a directive in a JavaDoc
		+	or to an embedded TODO comment. Every KI can be associated with an entire class, a specific member, or even a
		+	selection within the member. Every KI can also be assigned
		+	a single type from a predefined set similar to that of Sec. 3.
		+	The type can be used to facilitate input, presentation, and
		+	filtering, but generally serves informational purposes.
		+
		+	One type of KIs in the client’s knowledge space are ''internal'' KIs , which reflect directives that are currently tagged
		+	in source files within the workspace. Since the code must be
		+	available and modifiable, such KIs are most appropriate for
		+	project artifacts and libraries. We borrow the syntax used
		+	in TAGSEA [10], and allow authors to create ''tag lines'' of
		+	the form <code>@tag TYPE: TEXT</code>. These lines will typically be
		+	added in the method’s documentation block and replace or
		+	mirror directives in the text
		+
	[[Category:Article]]		[[Category:Article]]

@@ Line 249: / Line 249: @@
 frame, add it to a container”, or “Cursor must be on the
 insert row before this call”.
 '''Locking:''' Some methods present clear synchronization
 requirements for their use [13].
 '''Parameters and return values:''' While all methods are
@@ Line 294: / Line 292: @@
 is set up”, or “names should be provided to avoid querying
 the entire registry”.
 [[Category:Article]]

← Older revision		Revision as of 14:56, 16 May 2019
Line 159:		Line 159:
	and discuss current research directions in Sec. 9		and discuss current research directions in Sec. 9

		+	==Method documentation in JAVA==
		+	Methods in JAVA are documented via a ''JavaDoc comment block'' placed just before their declaration in the source
		+	code. Though any text is allowed, official guidelines [5, 12]
		+	recommend a specific structure: 1) A ''“summary sentence
		+	containing a concise but complete description of the API
		+	item”''. 2) An ''“implementation-independent description and
		+	specification that must include boundary conditions, parameter ranges and corner cases.”''. 3) A series of tagged
		+	lines that list parameters, return values, exceptions, and
		+	other metadata, even if they are obvious or redundant with
		+	the documentation text.
		+
		+	While the documentation of every class in the API is typically provided as an HTML file generated by the JavaDoc
		+	tool, most IDEs provide means to read the JavaDocs
		+	of specific methods from within the editor. Selecting a
		+	method from a class outline or auto-complete list presents
		+	its JavaDocs, but more importantly, hovering over a call
		+	presents the JavaDocs of its target in a tooltip window,
		+	which we call the JavaDoc hover.
		+
		+	In our survey of APIS we found many materials that
		+	bloat JavaDocs and might make directives even more difficult to spot. These include general descriptions that would
		+	fit better at the class level, and implementation details that
		+	are only relevant to maintainers. A prevalent problem with
		+	the JavaDocs of toolkits that rely on subclassing, such
		+	as SWING, is that they mix the information relevant to
		+	clients of a class instance with information that is relevant
		+	only to subclass developers who override the method.
		+
		+	The subclassing mechanism also presents significant
		+	challenges for the consumption of documentation. In
		+	object-oriented languages like JAVA, polymorphism [7] allows a variable declared with a certain type (termed static
		+	type) to contain at runtime instances of subtypes (called dynamic types). When a method is invoked on the variable and
		+	there is an overriding version in a dynamic type, the latter
		+	is invoked. However, since the dynamic type of a variable
		+	cannot be predicted and as it may change during runtime,
		+	the actual target of such calls cannot be determined.
		+
		+	For this reason, most IDEs merely present the JavaDocs
		+	for the static target, potentially leaving users unaware of
		+	new or conflicting directives in an overriding version. This
		+	can have severe consequences if conformance [7] is violated
		+	and the documented behavior of the overriding version conflicts with that of the overridden. Though deprecated, we
		+	encountered such violations even in quality library code.
		+
		+	==Directives==
		+	Though directives play a central role in our approach,
		+	there are no strict criteria to distinguish knowledge that
		+	should be “pushed” into the awareness of clients from
		+	materials that can “wait” for the user to actively seek
		+	them. These decisions ultimately fall to whoever creates
		+	the eMoose knowledge-items for that API. Our intention,
		+	however, is for candidate directives to meet two requirements. First, they must demand or imply concrete steps
		+	which the client can follow and for which it is straightforward to come up with a violating example. Second,
		+	they should capture nontrivial, infrequent, and possibly unexpected information. For example, since many methods
		+	specify policies for null argument values, these policies
		+	should not be considered directives.
		+
		+	We note that in our survey of standard APIS, many directives were relatively straightforward to identify and distinguish from the rest of the narrative. Authors frequently used
		+	the imperative to address clients or talked about them in
		+	the passive. They also frequently emphasized these clauses
		+	with phrases such as be aware that or note that, and words
		+	such as must, should, warning, etc. Most difficulties in determining whether a clause constituted a directive occurred
		+	when such constructs were not used.
		+
		+	To illustrate the breadth of important issues covered by
		+	directives, we now present prominent types which we frequently encountered in our survey of API documentation.
		+
		+	We begin with ''imperative directives'', which represent
		+	contract elements whose violations can have immediate
		+	consequences, delayed and unpredictable runtime effects,
		+	or future compatibility and extension issues.
		+
		+	'''Restrictions:''' Many methods explicitly restrict the set
		+	of clients and contexts from which they may safely be invoked, such as “do not call from UI thread” or “for use only
		+	by debugging code”. Interestingly, many of these restrictions are defined in abstract and human-readable terms that
		+	would complicate formal specification and automated conformance checking. For instance, some refer to conceptual
		+	sets of artifacts that may be difficult to enumerate, such as
		+	“toolkit code” or “debugging infrastructure”, and others to
		+	program states that are difficult to evaluate, such as: “only
		+	from actions that are installed on a button”.
		+
		+	'''Protocols:''' Many methods are designed to be used as
		+	part of a sequence of actions that set or transform the object’s state. Their documentation includes protocol constraints that specify what should occur before and after the
		+	call. Common examples state that the method must only be
		+	called once, or that it must be called prior to or only after a
		+	call to some other method. As with restrictions, many protocols are described in general natural text descriptions that
		+	would be difficult to formally specify and validate. For example: “All data in returned stream must be read prior to
		+	getting value of other column”, “To reuse a closed internal
		+	frame, add it to a container”, or “Cursor must be on the
		+	insert row before this call”.
		+
		+
		+	'''Locking:''' Some methods present clear synchronization
		+	requirements for their use [13].
		+
		+
		+	'''Parameters and return values:''' While all methods are
		+	expected to specify the nature and ranges for all parameters and return values, some convey unexpected restrictions
		+	or requirements which can be considered directives. For
		+	instance, the replaceAll method in String warns users
		+	from including $ and \ characters in the replacement string,
		+	since it is implemented via regular expressions. Many methods that receive or return complex objects or platform resources indicate whether internal copies are used, and what
		+	the disposal responsibilities are.
		+
		+	We now turn to directives that are more informative in
		+	nature. These are meant to be taken into consideration but
		+	not necessarily acted upon, and may therefore be outside
		+	the domain of tools for automatic conformance checking.
		+	In some cases, however, ignoring these directives can lead
		+	to actual errors.
		+
		+	'''Alternatives:''' The documentation of some methods suggests that a different method be used. Though often related to encapsulation or deprecation, some alternatives offer fundamentally different functionality, so a lack of awareness may result in breakdowns. For example, the JavaDocs
		+	for putLayer in SWING’s JLayeredPane suggest using setLayer to get “desired side-effects like repainting”.
		+
		+	'''Limitations:''' Some methods are less robust and comprehensive than their name may suggest; they may specifically
		+	delineate the inputs or situations they are capable of handling or describe limitations on their outputs. Other methods explicitly announce that certain events or side effects
		+	will not occur. For instance, adding or removing items
		+	from SWING containers does not cause visual change until ''validate'' is called.
		+
		+	'''Side effects:''' Some methods have additional effects to
		+	those conveyed in their signature and summary sentence.
		+	For example, many getters perform lazy creation. Setting
		+	certain properties in SWING automatically sets additional
		+	properties. Changing the row sorter in a <code>JTable</code> will also
		+	clear selections and reset row heights. Disposing of the last
		+	displayable window in the JVM may terminate it.
		+
		+	'''Performance:''' Some methods use algorithms or services
		+	that have performance implications of which clients must
		+	be aware. For example, many methods return copies of
		+	complex objects and therefore suggest caching or avoiding
		+	excessive calls. Other examples include: “should only be
		+	called on highly available system unless a progress monitor
		+	is set up”, or “names should be provided to avoid querying
		+	the entire registry”.
	[[Category:Article]]		[[Category:Article]]

@@ Line 12: / Line 12: @@
 <div class="noautonum">__TOC__</div>
-==Abstract==
+'''Abstract'''
 ''The documentation of API functions typically conveys detailed specifications for the benefit of interested readers. In some cases, however, it also contains usage directives, such as rules or caveats, of which authors of invoking code must be made aware to prevent errors and inefficiencies. There is a risk that these directives may be “lost” within the verbose text, or that the text would not be read because there are so many invoked functions. To address these concerns for Java, an Eclipse plug-in named eMoose decorates method invocations whose targets have associated directives. Our goal is to lead readers to investigate further, which we aid by highlighting the tagged directives in the JavaDoc hover. We present a lab study that demonstrates the directive awareness problem in traditional documentation use and the potential benefits of our approach.''