Bug ID: JDK-4770541 stddoclet: Add links from packages, classes and members to online examples

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 6

Priority: P4
Status: Resolved
Resolution: Duplicate
OS: other
CPU: generic

Submitted: 2002-10-29
Updated: 2014-05-05
Resolved: 2014-02-20

Improving the ability to find examples is one of the most highly 
requested features of developers using our website according to 
Sun studies.  We can take a giant step toward fixing this for the J2SE 
by adding links to online examples.

Proposal:
In javadoc, we add links called "See examples" in three places:

  1) in a package description
  2) in a class description
  3) in a member description

Not all packages, classes, or member will have a "see examples"
link -- only ones with examples.

If you click on a link, you'll see a page that sorta looks like:

  Java Tutorial
     How to blah, blah...
     Looking at blah, blah...
     Finding the blah, blah...
     See all X matches

  Java Almanac
     e423. Quintessential Regular Expression Search Program
     e424. Determining If a String Matches a Pattern Exactly
     e425. Applying Regular Expressions on the Contents of a File
     e426. Removing Duplicate Whitespace in a String
     e427. Greedy and Nongreedy Matching in a Regular Expression
     e428. Escaping Special Characters in a Pattern
     See all X matches

  Tech Tips
     ....
     ....
     See all X matches

We will look at ways to documenting examples in JDK9. This is a duplicate of 4075480.

20-02-2014

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mustang

14-06-2004

EVALUATION This is do-able for 1.4.2. ###@###.### 2002-10-29 Here's generally what would need to be done. Javadoc reads in an example-list file consists of package names, class names, and member names that have examples. This file is used to determine whether or not a "see examples" link is displayed. Approach 1: Add a couple more flags: -examplefile <file> -examplelink "http://....?q=" Approach 2: Put the example link URL in the example-list file, so the -examplelink option is not needed. Approach 3: Add no new options, but simply read in a file name example-list that's located in the top-level doc-files directory. When javadoc generates a "see example" link, it appends the current program element (package, class or member) to the link, such as: http://java.sun.com/docs/redirect/egsearch?q=java.util.regex http://java.sun.com/docs/redirect/egsearch?q=java.util.regex.Matcher http://java.sun.com/docs/redirect/egsearch?q=java.util.regex.Matcher.lookingAt For the online javadocs, the example link will refer to a redirect that goes to the example-search-aggregator page. This page does focused searches on different collections (tutorial, tech tips, etc.) and different sites (javaalmanac, etc) and then summaries the result as above. In terms of starting out with something simple, I recommend that the "see examples" link first go to the javaalmanac site as in: http://dev.javaalmanac.com/cgi-bin/search/find.pl?words=java.util.regex http://dev.javaalmanac.com/cgi-bin/search/find.pl?words=java.util.regex.Matcher http://dev.javaalmanac.com/cgi-bin/search/find.pl?words=java.util.regex.Matcher.lookingAt so we can start getting feedback. I would estimate the coverage at javaalmanac.com to be around 50% for classes and 10% for all members, covering the most-requested elements (not counting CORBA). ###@###.### 2002-10-29 (for patrick.chan) There are two approaches: - static links - as described above, the links are hard-coded when javadoc is run. The drawback is that we can't add example links to elements after we run javadoc. - dynamic links - use javascript to display the links, and when a class page is loaded, the links would check a local file whether to display or not. We could then add to the links at any time by publishing a new file. Or if there's not too much latency, publish the file on the Internet for the class page to check. ###@###.### 2002-10-29 We would like to consider implementing tag lists in a generalized way that could substitute for any standard or custom tags present in doc comments. (For example, someone could use it to add author names without adding tags.) We could do a partial, minimum implmentation for 1.4.2 that either has no command line options (reads a file named example-list that's located in the top-level doc-files directory), or has an option that points to the tag list file. The tag list feature might (eventually?) be built into the javadoc tool so the tags are simply added to the tag array returned by Doc.tags(), along with the hard-coded tags. ###@###.### 2002-10-30 CCC Proposal: The information needed to add the "See Example" links would be in an XML file located at src/docs-files/tag-list.xml of the J2SE source tree that would automatically be looked for and loaded if it exists. The file would be of this form: <tags> <tag-attribute tagname="examplelink" name="url" value="http://java.sun.com/docs/redirect/j2se/examples" /> <program-element name="java.util.Map"> <tag name="examplelink" value="" /> </program-element> </tags> The source code (TagList.java) to parse this file has already been written. This example defines a tag named "examplelink" and includes a base URL that points to the example website (through a redirect). Each program element has its own <program-element> tag giving the name and type of tag ("examplelink") it responds to. The full URL to the example is created by appending the program element name to the base URL. The base URL would actually be to a redirect that initially points to javaalmanac.com, but would eventually point to a list likely including the Java Tutorial and Java Tech Tips. At javaalmanac.com, the current coverage for 1.4 is around 50% for classes and 10% for all members, covering the most popular and requested program elements (not counting CORBA). This site is written and run by Pat Chan, who adds to the coverage by writing examples on demand. We would implement a -taglistfile (or -taglist) option which would accept a URL or path that points to the file tag-list.xml file in place of looking in the default location src/docs-files/tag-list.xml As far as the examples are concerned, we would run this proposal by the conformance council to confirm they are okay with the J2SE spec containing links to non-spec material, and whether the "spec" diffs generated by adding these links to the spec have to go through a 30-day public JCP maintenance review. If the examples are desirable, and it is deemed that that we neeed Sun engineers to review the examples, we would then go to engineering managers to seek their approval for review of the examples, which could be done as a background task over several months, which means we would miss the Mantis train, and could instead shoot for Tiger. CCC Decision: "Reject. All examples added to the J2SE specification, whether directly or by reference, should be reviewed by J2SE Engineering. This request should therefore be deferred to Tiger." ###@###.### 2002-11-08

08-11-2002