Improving API documentation usability with knowledge pushing

Uri Dekel, James D. Herbsleb
2009 2009 IEEE 31st International Conference on Software Engineering  
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
more » ... -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.
doi:10.1109/icse.2009.5070532 dblp:conf/icse/DekelH09 fatcat:is3legmsnbc5jem4xy6o5yhywu