Clojure

Javadoc for public Java API

Details

  • Type: Enhancement Enhancement
  • Status: Closed Closed
  • Priority: Critical Critical
  • Resolution: Completed
  • Affects Version/s: None
  • Fix Version/s: Release 1.6
  • Component/s: None
  • Labels:
  • Patch:
    Code
  • Approval:
    Ok

Description

Publish javadoc for http://dev.clojure.org/jira/browse/CLJ-1188.

  • Add javadoc for public API classes (Clojure and IFn)
  • Add ant build target to generate the javadoc
  • Publish javadoc to the clojure project github pages (will be done manually)

Patch: clj-1190-3.diff (javadoc updates and a new Ant target)

Screened by: Stuart Halloway

Updated by: Alex Miller (moved clojure.api.API to clojure.java.api.Clojure and tweaked one example per Rich's suggestion)

  1. clj-1190-3.diff
    05/Dec/13 10:54 AM
    17 kB
    Alex Miller
  2. clj-1190-2.diff
    23/Oct/13 10:47 PM
    6 kB
    Alex Miller
  3. clj-1190.patch
    23/Oct/13 8:47 PM
    1 kB
    Alex Miller

Activity

Hide
Andy Fingerhut added a comment -

It seems that when this ticket is completed, it may also complete CLJ-19, too.

Show
Andy Fingerhut added a comment - It seems that when this ticket is completed, it may also complete CLJ-19, too.
Hide
Alex Miller added a comment - - edited

Maven javadoc is something like this (configuration as in http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html):

<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9.1</version>
        <configuration>
          <show>public</show>
          <verbose>true</verbose>
          <sourceFileIncludes>
            <include>API.java</include>
          </sourceFileIncludes>
          <sourcepath>${basedir}/src/jvm/clojure/api</sourcepath>
        </configuration>
      </plugin>

What is desired for inclusion in the javadoc? Just the clojure.api package and API class? If so is it worth automating the publishing of this API or just documenting a process to put someplace static?

Show
Alex Miller added a comment - - edited Maven javadoc is something like this (configuration as in http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html):
<plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9.1</version>
        <configuration>
          <show>public</show>
          <verbose>true</verbose>
          <sourceFileIncludes>
            <include>API.java</include>
          </sourceFileIncludes>
          <sourcepath>${basedir}/src/jvm/clojure/api</sourcepath>
        </configuration>
      </plugin>
What is desired for inclusion in the javadoc? Just the clojure.api package and API class? If so is it worth automating the publishing of this API or just documenting a process to put someplace static?
Hide
Alex Miller added a comment -

Javadoc can be told what to doc either by package or by java source file. The Maven plugin only supports the source file version if the files are in the same directory (as far as I can tell).

Ant was a little easier to get going:

<target name="javadoc" depends="build"
         description="Creates javadoc for Clojure API.">
    <javadoc destdir="javadoc">
      <classpath>
        <path location="${build}"/>
      </classpath>
      <fileset dir="src/jvm">
        <include name="clojure/api/API.java"/>
        <include name="clojure/lang/IFn.java"/>
      </fileset>
    </javadoc>
  </target>

However, there is no way to omit the nested IFn primitive interfaces in either case. That's just not a thing. Presumably it would be possible to customize the standard doclet to omit whatever you wanted although it makes me throw up in my mouth a little to even suggest that as a necessity.

Show
Alex Miller added a comment - Javadoc can be told what to doc either by package or by java source file. The Maven plugin only supports the source file version if the files are in the same directory (as far as I can tell). Ant was a little easier to get going:
<target name="javadoc" depends="build"
         description="Creates javadoc for Clojure API.">
    <javadoc destdir="javadoc">
      <classpath>
        <path location="${build}"/>
      </classpath>
      <fileset dir="src/jvm">
        <include name="clojure/api/API.java"/>
        <include name="clojure/lang/IFn.java"/>
      </fileset>
    </javadoc>
  </target>
However, there is no way to omit the nested IFn primitive interfaces in either case. That's just not a thing. Presumably it would be possible to customize the standard doclet to omit whatever you wanted although it makes me throw up in my mouth a little to even suggest that as a necessity.
Hide
Stuart Halloway added a comment -

Including nonpublic interfaces is worse than having no Javadoc at all, IMO. We plan to change this API almost never, so one possibility it to just generate from a copy of the IFn source file that omits the primitives.

API should have a class level document.

The goal here is to publish the official Javadoc on the web. Following the javadoc jar convention is a potential separate goal, but out of scope here.

Show
Stuart Halloway added a comment - Including nonpublic interfaces is worse than having no Javadoc at all, IMO. We plan to change this API almost never, so one possibility it to just generate from a copy of the IFn source file that omits the primitives. API should have a class level document. The goal here is to publish the official Javadoc on the web. Following the javadoc jar convention is a potential separate goal, but out of scope here.
Hide
Alex Miller added a comment -

When I next get a chance I'll take a look at what customizing the standard doclet would take. If it looks ugly I'll bail out.

Show
Alex Miller added a comment - When I next get a chance I'll take a look at what customizing the standard doclet would take. If it looks ugly I'll bail out.
Hide
Alex Miller added a comment -

Modifying the standard doclet (a mystery shrouded in a thicket of Oracle docs) to generate javadoc for 2 classes is ridiculous. As Stu suggested, I just hacked the inner interfaces out of IFn and generated the attached javadoc with the ant target prior in the comments. I think we could probably turn off a few more of the bits and improve the title,etc then manually publish this set of files in the github pages somewhere.

Show
Alex Miller added a comment - Modifying the standard doclet (a mystery shrouded in a thicket of Oracle docs) to generate javadoc for 2 classes is ridiculous. As Stu suggested, I just hacked the inner interfaces out of IFn and generated the attached javadoc with the ant target prior in the comments. I think we could probably turn off a few more of the bits and improve the title,etc then manually publish this set of files in the github pages somewhere.
Hide
Alex Miller added a comment -

Added an Ant build target that strips the inner interfaces of IFn and generates the javadoc. Still need to add class javadoc for both API and IFn.

Show
Alex Miller added a comment - Added an Ant build target that strips the inner interfaces of IFn and generates the javadoc. Still need to add class javadoc for both API and IFn.
Hide
Alex Miller added a comment -

Added a new patch that adds javadoc for the clojure.lang package, the IFn and API classes. It also has an Ant task that generates the javadoc in target/javadoc which you can run with ant javadoc.

Show
Alex Miller added a comment - Added a new patch that adds javadoc for the clojure.lang package, the IFn and API classes. It also has an Ant task that generates the javadoc in target/javadoc which you can run with ant javadoc.
Hide
Alex Miller added a comment -

The API will live here (prelim version there now): http://clojure.github.io/clojure/javadoc/

Show
Alex Miller added a comment - The API will live here (prelim version there now): http://clojure.github.io/clojure/javadoc/
Hide
Rich Hickey added a comment -

We should never show things like (lookup and simultaneously use var):

API.var("clojure.core", "deref").invoke(printLength);

because people will put that in a loop.

Also, API.var seems like a lot of CAPS. I understand that's proper Java conventions but maybe we need to pick another name?

Show
Rich Hickey added a comment - We should never show things like (lookup and simultaneously use var):
API.var("clojure.core", "deref").invoke(printLength);
because people will put that in a loop. Also, API.var seems like a lot of CAPS. I understand that's proper Java conventions but maybe we need to pick another name?
Hide
Alex Miller added a comment -

At Stu's request, I made the updates from our prior conversation, namely:
1) Moved clojure.api.API to clojure.java.api.Clojure and updated all references.
2) Made the example change suggested by Rich to avoid creating and invoking the var in one step.

Show
Alex Miller added a comment - At Stu's request, I made the updates from our prior conversation, namely: 1) Moved clojure.api.API to clojure.java.api.Clojure and updated all references. 2) Made the example change suggested by Rich to avoid creating and invoking the var in one step.
Hide
Alex Miller added a comment -

Andy, please let me know before modifying screened patches as they need to be re-screened.

Show
Alex Miller added a comment - Andy, please let me know before modifying screened patches as they need to be re-screened.
Hide
Alex Miller added a comment -

In this case, it looks like you didn't leave the old one so I'm not even sure what's different?

Show
Alex Miller added a comment - In this case, it looks like you didn't leave the old one so I'm not even sure what's different?
Hide
Alex Miller added a comment -

Oh, I'm misreading the comment history, you just changed the patch field. Carry on.

Show
Alex Miller added a comment - Oh, I'm misreading the comment history, you just changed the patch field. Carry on.

People

Vote (0)
Watch (1)

Dates

  • Created:
    Updated:
    Resolved: