Javadoc is a Tool - Not a Document

This morning I innocently answered an email from a colleague who was referring to the Access Manager Java API documentation as JavadocTM (without the trademark but this is the first use of the term in this entry outside of the header). In my reply I referred back to the Java API documentation as JavaDocs. In the reply back to me, I was chastised (in a kindly manner) for using the term JavaDocs and not Javadoc. I, of course, had to defend my honor. Here was my reply:

Don't get me started on this one. OK, you did.

Javadoc is the tool that is used to generate the HTML pages that when viewed as a piece are often referred to, incorrectly, as Javadoc. These HTML pages should not be referred to as Javadoc, Javadocs, JavaDocs, or anything remotely spelled as such. Javadoc is a trademarked name for a piece of software. You'll notice that since this was discovered by me the name given to these HTML pages in our doc sets (and registered as such in pubstool) is the Java API Reference. And if you click that link in the AM 71 doc set and see the generated HTML pages you'll note that the word Javadoc is nowhere to be found. As for the link you sent, here is the first sentence:

Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.

But no one listens to me.

Hey, I think I just wrote today's blog entry.

In 2002, we decided to publish the engineering comments generated using the Javadoc tool for Identity Server 6.0. This was new territory as no other documentation team was publishing these pages yet. I was given the task of editing these comments and filing bugs against them when necessary. In my research, I found out about the trademark and common misuse of the term Javadoc and brought it up at our team meeting. For the February 2004 release, Access Manager 6 2005Q1, we renamed the book as the Java API Reference. In fact, we liked the name so much that in our next release we renamed the guide that discussed the C API, the C API Reference.

As for why I used the term JavaDocs in my reply: it was internal email to a small group who had already used the term. I was innappropriately cutting keystrokes.

Not that there's anything wrong with that.
Comments:

Post a Comment:
Comments are closed for this entry.
About

docteger

Search

Categories
Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today