Categories
Eclipse

Setup a Git-hosted Project in Eclipse

If you’re used to using Visual Studio and Source Depot, then you’re in for a bit of a paradigm shift when you use Eclipse and git.

Note: The location of your Eclipse Workspace, and the location of your source code are mutually exclusive. I.e., you might think that the workspace should encompass your local git repo – but it doesn’t, and actually can’t. For example, I have all of my local repos on the C: drive (in C:\Users\Chris\src\), yet I have my default Workspace on my A: drive (in A:\Documents\Eclipse\Projects\).

Think of it like this: when a multi-media app manages your music collection, it doesn’t move all of your media files into it’s program directory. Instead, it builds a database the contains records for corresponding media files. Each record contains a pointer to the media file, along with all of the details contained in its ID3 tag.

You’re doing something similar when you build an Eclipse Workspace. In the case of Eclipse though, the database is stored in a “Workspace;” a folder on your file system that contains a folder called “.metadata”.

Window > Preferences > Teams > Git

Default Repository Folder (Git_HOME):

${env_var:GITSOURCE}/

Eclipse reads these details straight from your user configuration file (%USERPROFILE%.gitconfig).

The only thing I had customized in this file was my merge tool: “C:\Program Files (x86)\Beyond Compare 4\BCompare.exe”

[user]
name = Chris Boorman email = cboorman@3rdParty.com
[diff]
tool = bc
[difftool “bc”]
path = C:\Program Files (x86)\Beyond Compare 4\BComp.exe
[merge]
tool = bc
[mergetool “bc”]
cmd = “C:\Program Files (x86)\Beyond Compare 4\BComp.exe” “$LOCAL” “$REMOTE” “$BASE” “$MERGED”
[push]
default = simple

To work on Git-hosted projects in Eclipse, you must import them into Eclipse using the Git Project Import Wizard. You can use Import Existing Project.

The procedure differs between projects hosted publicly on GitHub, and projects hosted on 3rdParty’s private repo server.

3rdParty private server

Here’s how to get a local enlistment to the privately hosted 3rdParty REST API Git repository. Before you begin, establish a VPN connection to 3rdParty.

  1. In Eclipse, open the Git perspective.
  2. In the Git Repositories pane, click Clone a Git repository
    The Clone Git Repository dialog appears.
  3. In the Connection Protocol drop-down list, select git.
  4. In the URI field, type the URI of the Git repository, and then click Next.
    git@git.c11.3rdParty.com:python_rest_api.git

    You’re prompted to input your password.

  5. In the Information dialog, type your SSH Passphrase, and then click OK.
    The Branch Selection dialog appears.
  6. Select branches to clone from the remote repository. Remote tracking branches are created to track updates for these branches in the remote repository.
    Click Deselect All, and then check the following branches: develop, feature/api_doc, master, release/current; and then click Next.
    The Local Destination dialog appears.
  7. Set the Initial branch to feature/api_doc, and then click Finish.
  8. In Eclipse, in the Project Explorer, right-click the background, and select Import > Import > Git > Projects from Git > Existing Local Repository.
    The Select a Git Repository dialog appears. Note that the repository you want isn’t in the list! Don’t worry though…
  9. Click Add.
    The Add Git Repositories dialog appears. The new repository is already checked (and in my case – along with the Java repo).
  10. Click FinishNext.
  11. Select Import as a General Project, and click Next.
    The new project folder appears selected: Working Directory – C:\Users|Chris\src\mobile_assets
  12. Accept the suggested project name (mobile_assets), and click Finish.

3rdParty on GitHub

To work on a project hosted on GitHub:

  1. Navigate to that project repo on GitHub.
  2. Click Fork. This creates a copy of the project repository under your account.
  3. Navigate to your new forked project on GitHub, and click Clone. This creates a local copy of the project repository on your hard drive.
Categories
Eclipse

Update Eclipse

The Updater service in Eclipse is based on Equinox p2, the Equinox framework OSGi implementation.

The OSGi (Open Service Gateway initiative) specification describes a modular system and a service platform for the Java programming language that implements a complete and dynamic component model, something that does not exist in standalone Java/VM environments.

When you run Help > Check for Updates, the Updater checks for system and component (addin) updates according to a list of “Available Software Sites” – which are p2 repositories. p2 stand for “Provisioning”.

Preferences > Install/Update > Available Software Sites

In my experience, this mechanism is buggy. You have to manually tweak the list (by adding, deleting, and editing) the items in the list.

http://wiki.eclipse.org/Eclipse_Project_Update_Sites

Here’s a list of URLs that you can visit to find the latest Update URI for a particular component.

<?xml version=”1.0″ encoding=”UTF-8″?>
<bookmarks>

<site url=” https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”ADT Plugin”/>

<site url=” http://download.eclipse.org/webtools/updates” selected=”true” name=”Eclipse Web Tools Platform Repository”/>

<site url=” https://sourceforge.net/projects/eclipsejsonedit/files/update” selected=”true” name=”eclipse-json-editor”/>

<site url=” http://e-p-i-c.sf.net/updates/” selected=”true” name=”EPIC – Perl Editor and IDE for Eclipse”/>

<site url=” http://nextinterfaces.com/http4e/install/” selected=”true” name=”HTTP4e”/>

<site url=” http://download.eclipse.org/mylyn/releases/luna” selected=”true” name=”Mylyn for Eclipse Luna”/>

<site url=” http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen XML Editor Install”/>

<site url=” http://pydev.org/updates/” selected=”true” name=”PyDev Update Site”/>

<site url=” http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/>

<site url=” http://download.eclipse.org/releases/luna/” selected=”true” name=”The Eclipse 4.4 (Luna) Updates”/>

<site url=” http://download.eclipse.org/webtools/repository/luna” selected=”true” name=”The Eclipse Web Tools Platform (WTP) software repository”/>

<site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse” selected=”true” name=”update site:  http://www.oxygenxml.com/InstData/Editor/Eclipse“/>

</bookmarks>

Categories
Eclipse

Customize Eclipse with Addins

You can enhance Eclipse’s standard functionality by adding addins.

Help > Install New Software…

Work with: –All Available Sites–

Peruse the list that appears – and pick out the plugins that you want.

Get for sure

The oXygen XML Editor for Eclipse plugin adds so many useful features to Eclipse, that I bought a license for myself. It gives you a ton of editors (e.g., HTML), and each one runs against the associated DTD or schema to ensure that your code is well formed.

  1. Get the latest version of the oXygen XML Editor for Eclipse by visiting: Download oXygen XML Editor.

    The download landing page is a bit confusing. Scroll up to the top of the page and simply click the Download button.

    Another web page appears, prompting you to fill in a form. Ignore it – the download begins automatically.

    Click Save instead of Open – in case there’s a problem with the download.

    The download takes about ten minutes.

  2. After downloading the corresponding archive, use 7-Zip to extract its content into the “dropins” subfolder of the Eclipse folder.

  3. Restart Eclipse.

    Eclipse discovers the new addin and configures it for you.

Update the oXygen XML editor plugin

Help > Install New Software…

Add the oXygen XML Editor software update endpoint URI: http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml

Paste this URI into the Work with field, and then click Add. The main window shows the work “Updating…”. When it is done, the list of updates, per Eclipse version displays. Check the box beside the latest version, and then click Next. The updates download and install, and then you must restart Eclipse for the changes to take effect.

Install PyDev from the Eclipse Marketplace

After you install PyDev, you’ll be asked to reboot Eclipse.

Open the PyDev perspective to make sure that it installed properly.

When you reboot Eclipse, Eclipse might discover that PyDev has an incomplete configuration. If it does, then it presents you with choices for configuring it (Auto, Manual, Quick Auto, etc.). Choose Quick Auto.

You need this so you can run Sphinx and rebuild the docs for the 3rdParty REST API docs. You need the ReST Editor to configure a build configuration that will run make.bat.

The ReST Editor is an Eclipse plugin, and it adds a pretty reStructuredText editor to the Eclipse IDE. This is useful for authoring documentation for Python projects, where you use the Sphinx doc builder to automatically generate help builds.

Install it from the Eclipse MarketPlace.

The ReST Editor project is an open source project, and the code is hosted on the project site.

Note: The ADT plugin for Eclipse in no longer the official IDE for Android development; it’s now Android Studio, so you should install it at some point.

Follow the procedure on the “Installing the Eclipse Plugin” web site: http://developer.android.com/sdk/installing/installing-adt.html

Configuration

Target Location for the Android SDK:

%POSIX_HOME%\android-sdks

Add new software

  • eclipse : the Eclipse update site, accessible via the URL : http://resteditor.sourceforge.net/eclipse.

An Addin to Tryout

Modelling > Sphinx SDK (Incubation) Modelling > UML2 Extender SDK Programming Languages > Javascript Development Tools Programming Languages > PHP Development Tools (PDT)

Categories
Eclipse

Configure Eclipse on First Launch

The first time you run Eclipse, you’re presented with a dialog that allows you to select a Workspace.

Workspace

Accept the default location for your Workspace.

%USERPROFILE%\workspace

Check “Use this as the default and don not ask again”.

Note: If you’re reinstalling Eclipse, you mustn’t reuse the same default location for your workspace – this will corrupt your Eclipse installation. I learned this the hard way because I’d been using C:\Users\Chris\workspace, and I wanted to use that directory again; so I made a copy of it and saved it (into E:\Safe\workspace), and then cleaned C:\Users\Chris\workspace.

Check for updates

Before you start installing addins to Eclipse, make sure you’re working with the latest version (build) of Eclipse.

  • To update Eclipse, click Help > Check for Updates

    Check the Status Bar for the update task’s progress.

Set preferences

In Eclipse, click Window > Preferences, and then systematically go through the items in the hierarchical menu in the left pane – and check each item’s configuration.

General

Appearance

Enable: Enable Animations

Compare/Patch/ > Text Compare

Enable: Initially show ancestry pane

Error Reporting

Enter your name and e-mail address

Workspace

Enable: Save automatically before build

Enable: Show workspace path in window title

Text file encoding: Other > UTF-8

Ant

Editor

Enable: Mark occurrences of the selected element in the current buildfile

Install/Update

Automatic Updates

Enable: Configure Eclipse so it automatically updates each time you start it.

Java

Editor

Folding

Enable: Comments, Inner types, and Members

Hovers

Enable: Combined Hover

Typing

Enable: Automatically insert at correct position > Semicolons > Braces

Team

Enable: Show the file author in compare editors

Git

History

Enable: E-mail addresses in Author/Committer columns

Update errors

If the update process fails, throwing errors like this:

No repository found containing: osgi.bundle,org.eclipse.aether.api,1.0.1.v20141111

No repository found containing: osgi.bundle,org.eclipse.aether.connector.basic,1.0.1.v20141111

No repository found containing: osgi.bundle,org.eclipse.aether.impl,1.0.1.v20141111

Then you need to refresh the list of “Available Software Sites.”

To do so, select them all in Preferences > Install/Update > Available Software Sites, and then click Remove.

Any easy way to add them back is to Import the file named bookmarks.xml with the following content:

bookmarks.xml
<?xml version=”1.0” encoding=”UTF-8”?>
<bookmarks>
<site url=”https://dl-ssl.google.com/android/eclipse/” selected=”true” name=”Android Developer Tools (ADT)”/>
<site url=”http://download.eclipse.org/recommenders/updates/stable/” selected=”true” name=”Code Recommenders Stable Update Site”/>
<site url=”http://download.eclipse.org/releases/luna/” selected=”true” name=”Eclipse Luna”/>
<site url=”http://www.oxygenxml.com/InstData/Editor/Eclipse/site.xml” selected=”true” name=”oXygen”/>
<site url=”http://pydev.sf.net/updates/” selected=”true” name=”PyDev Update Site”/>
<site url=”http://resteditor.sourceforge.net/eclipse/” selected=”true” name=”ReST Editor Update Site”/>
<site url=”http://jautodoc.sourceforge.net/update/” selected=”true” name=”update site: http://jautodoc.sourceforge.net/update/”/>
</bookmarks>

Add common libraries

When I was experimenting with Java projects, I continually ran into instances where projects depended on external libraries (JSON, IO, etc.). After downloading a few of them, I simply downloaded several of them – so I’d always have then on hand.

To add the common libraries, visit:

 

Categories
Eclipse

Install Eclipse

  1. Get the latest version of Eclipse by visiting:  Eclipse Downloads.

  2. From the Eclipse Downloads landing page, click Eclipse IDE for Java Developers > Windows 64 Bit.

    When the Run/Save toast appears, click Save.

    When you click Run, the Eclipse Installer by Oomph runs.

  3. Accept the installer default installation directory:

    C:\java-neon
  4. Set the option “Run this program as an administrator” on the Eclipse executable (i.e., on the file “C:\opt\eclipse\eclipse.exe”).

  5. Pin the executable to the Taskbar. You can do this by Ctrl + clicking & dragging from File Explorer to the Taskbar.

    You’re done. Go ahead and launch Eclipse.

Categories
Eclipse

Requirement: Install the JDK First

Eclipse was written in Java, is hosted in a Java Virtual Machine, and was primarily designed for Java software development. As such, a fundamental requirement for running it is a Java Development Kit (JDK) deployment. The JDK is a superset of the Java Runtime Environment (JRE) – the bits you need in order to run Java applications.

  1. Get the latest version of the JDK by visiting: Oracle Java SE Downloads. There are several versions to choose from. Which one should you get? I recommend Java Platform, Standard Edition.
  2. On the Java SE Downloads page, in the section Java Platform, Standard Edition, click JDK Downloads. You land on the Java SE Development Kit 8 Downloads page.
  3. Accept the license agreement (click the “Accept License Agreement radio button), and then click the download link for the latest version of the Windows x64 release. When the Run/Save toast appears, click Run.
  4. Accept all defaults except the “install to” location; for that, see the next subsection.

Where to install

I’m going to follow the Linux Filesystem Hierarchy Standard and create an /opt directory on the root of my C: drive; and then I’ll install all of the open source software beneath it. The hope is to create a [somewhat] portable installation.

  1. The default location was C:\Program Files\Java\jdk1.8.0_60\, but I changed it to C:\opt\Java\jdk1.8.0_60\). I.e., in the fully-qualified path name, simply replace “Program Files” with “opt”.

Note: I was going to truncate the version number from the end of the path name, but I changed my mind: I thought there might be a good reason why Oracle included these details. I kept the version number for these docs because I felt it wasn’t that important that I genericize the docs by using jdkx.x.x_xx.

  1. Half-way through the JDK installation, the JRE installation begins, and the installer presents you with the option to change the install location from C:\Program Files\Java\jre1.80_66 to a different folder. Again, simply replace “Program Files” with “opt”.

In the case of the JRE, you can’t simply select Program Files and type opt over top of it. You’re forced to navigate a path selection dialog down to “C:\opt\Java”, and create a new folder (“\jre1.8.0_66” in my case).

Note: Interestingly, the installer actually installed three copies of the java runtime.

  • C:\opt\Java\jdk1.8.0_66\bin\java.exe (java runtime for private use by the IDE). * Choose this one for your JAVA_HOME in order to get the tools.jar to work!
  • C:\opt\Java\jdk1.8.0_66\jre\bin\java.exe (java runtime for private use) * I used to point JAVA_HOME here, but Ant doesn’t work if you do!
  • C:\opt\Java\jre1.8.0_66\bin\java.exe (java runtime for public use). Use this one for %JAVA_HOME%.

Note:  I also found java.exe in another location:

C:\ProgramData\Oracle\Java\javapath

… and this line was also added to the beginning of my path statement. I don’t know how this got there!?

Setup system environment variables

The use of System Environment Variables makes installations portable. To add new System environment variables:

  1. Right-click the Start button.

  2. Click Control Panel.

  3. Click System and Security.

  4. Click System.

  5. Click Advanced System Settings.

  6. In the System Properties dialog that appears, click Advanced > Environment Variables.

  7. Add the following two new System environment variables:

    POSIX_HOME = C:\opt\
    JAVA_HOME = %POSIX_HOME%\Java\jdk1.8.0_66\

Note: In order to get Ant to work properly, you have to set JAVA_HOME to point to the java.exe in the JDK – so Ant can find the file tools.jar.

Add the path to the Java executable to the path system environment variable

Adding the location of application executables to the Path statement makes them portable in that it gives you the flexibility of running pathed executables from any directory.

  1. Add the following string the end of the Path statement (i.e., to the Path System environment variable).

    ;%JAVA_HOME%\bin\

Note: The \bin directory contains the executable file java.exe.

Categories
Eclipse

Eclipse Cookbook

This cookbook is intended to be used for installing and configuring the Eclipse Integrated Development Environment (IDE) on Windows 10. I used Eclipse as part of my content management system because it allowed me to integrate a Git plugin (which in turn allowed me to version-control my content), and it allowed me to use the markdown editor plugin.

Key concepts

Before I go into the details, I thought it best to explain a few Eclipse concepts first.

Workbench

The term Workbench refers to the desktop development environment. The Workbench aims to achieve seamless tool integration and controlled openess by providing a common paradigm for the creation, management, and navigation of workspace resources. Each Workbench window contains one or more Perspectives. Perspectives contain Views and Editors, and control what appears in certain menus and tool bars. More than one Workbench window can exist on the desktop at any given time.

Workspace

Workspace is a conceptual construct. It’s a container for a multiple Eclipse projects.

Note: You must separate your Git repo from your Workspace (no overlap). Both are constructs for organizing project files, and conceptually, both exist in an abstraction layer on top of the file system. It’s important to understand the difference here because you’ll run into trouble later if you don’t keep the two paradigms separate.

Categories
CSS

CSS Cookbook

Class and ID attributes

These two attributes specify where and how styles are applied to elements.

Class

You use the class attribute to define styles for elements with the same class name. When you update the style definition, all elements in your document that have that class attribute are effected. Here’s an example of a class definition:

<style>
.cities {
  background-color: black;
  color: white;
  margin: 20px;
  padding: 20px;
}
</style>

Note: Notice the use of the period before the class name.

Here’s an example the demonstrates how to use a class attribute:

<body>
<div class="cities">
  <h2>London</h2>
  <p>London is the capital of England.</p>
</div>

ID

You use the id attribute to define a style for a unique (one-off) element. When you update the style definition, only one element is effected (the one with that ID attribute). Here’s an example of an ID definition:

<style>
#myTwoCents {
  background-color: lightblue;
  color: black;
  padding: 40px;
  text-align: center;
}
</style>

Note: Notice the pound sign before the ID name.

Here’s an example that demonstrates how to use an ID attribute:

<div id="myTwoCents">
  <p>I like traffic lights.</p>
</div>

Positioning

This sections explains how to control content flow within the page. For more information, see CSS position property.

static

The default positioning is static. Static positioned elements simply render in the order that they appear in the document flow. Static positioned elements are not affected by the topbottomleft, and right properties.

fixed

Fixed positioned elements:

  • are removed from the normal flow.
  • are positioned relative to the browser window,
  • will not move, even if the window is scrolled.
  • can overlap other elements.

Note: The document and other elements behave like the fixed positioned elements don’t exist.

relative

In the same way that fixed position allows you to place an element up against the browser window border, position relative allows you to do the same thing, but up against a container’s borders. Set the containing box’s position to relative, and then set the position of the box that it contains to absolute.

Example

If you set relative positioning on div-1, then any elements within div-1 are positioned relative to div-1. Then if you set absolute positioning on div-1a, then you can move it to the top right of div-1.

#div-1 {
        position:relative;
}

#div-1a {
        position:absolute;
        top:0;
        right:0;
        width:200px;
}

The element is positioned relative to its normal position, so “left:20” adds 20 pixels to the element’s LEFT position.

Notes

  • Relative positioned elements are often used as container blocks for absolute positioned elements.
  • If you want scroll bars, then don’t use relative position.
  • If you switch to relative, then you’ll loose the scroll bars.
  • To get scroll bars, set values for “top” and “bottom” (e.g., top: 120 px, bottom: 30 px), and then set the position to either fixed or absolute.

Absolute

Absolute positioned elements:

  • are positioned relative to their first positioned enclosing element (or body element, if there aren’t any).
  • are removed from the normal flow.
  • don’t participate in the normal flow of the static elements in the document.

Note

  • Absolute positioning doesn’t work for variable-height columns (boxes).
  • You can see the blue outline of a selected div only when you set it’s positioning to Absolute.
  • This is the type of position you want for the title in your page header. It allows you to move the text to the right, away from the logo (padding-left: 20 px).

Inherit

The value of the position property is inherited from the parent element.

Display

The display property specifies the type of rendering box used for an element.

Block

As far a flow is concerned, content won’t appear beside a block. As far as that block taking up all the available horizontal space – you have to specify width = 100%.

Margins and padding

  • Margins are used to setup a space around content to keep other content away.
  • Padding is used to distance content away from the sides of a container (e.g., a div).

Scroll bars

To get scroll bars to appear, and to force the div element to keep it’s shape: Overflow=scroll

Not sure

div#mainSection table {} Match any table that is within a division that has an id=mainSection. I.e., must match the entire division, not just an element.

Notes

Don’t confuse “.body” with “Body Text”. 🙂

Categories
Apache Ant Java

Apache Ant Cookbook

Apache Ant is a software tool for automating software build processes (like GNU Make). I used Ant to build the Adroid version of a doc set from within the Eclipse IDE.

Note: The name Ant is an acronym that stands for Another Neat Tool.

Installation and setup

The oXygen XML Editor uses it’s own version of Ant. To get oXygen to work properly, you have to make it’s Ant installation the primary Ant installation located in C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.

  1. Delete the standalone Ant in: C:\apache-ant-1.9.2.
  2. There’s another standalone version located in: C:\Users\Chris\.ant. Delete it.
  3. Leave Eclipse Ant in: C:\opt\eclipseplugins\org.apache.ant_1.9.2.v201404171502. You should leave this so you can set controls for it (i.e., set preferences in Eclipse). You can set it up to use oXygen’s Ant installation.

Set the environment variable

In Windows

  1. Create the new environment variable ANT_HOME=C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.
  2. Add it to the path statement: ;%ANT_HOME%/bin.

In Eclipse

  1. In Eclipse, navigate to: Windows > Preferences > Ant > Runtime.
  2. Click Ant Home….
  3. Navigate to C:\opt\eclipseplugins\com.oxygenxml.editor_16.1.0.v2014102117\tools\ant.
  4. Click Ok, then click Apply, and then click OK.

Update the Ant installation with the latest libraries and dependencies

Open a command prompt window (with Administrative privileges), and execute the following command:

ant -f fetch.xml -Ddest=system

Note: ant.bat is the batch file that serves as the wrapper script for Windows.

Ant script structure

Ant scripts have the following structure:

<Project>
        <Target>
                <Task>
                </Task>
        </Target>
</Project>

Doc build timestamp

I wanted each doc build to include the time that I generated the docs. For more information, see the documentation for tstamp. To accomplish this, you use the TODAY property in your Ant project, but first you need to initialize it. You do this by adding the following statement to your Ant project.

<tstamp/>

This sets the standard DSTAMPTSTAMP, and TODAY properties according to the default formats. I added it to the init target to make its use obvious.

<target name="init" description="Ant build project setup.">
        <tstamp>
                <format property="doc_build.time_stamp" pattern="EEEE MMMM dd, yyyy 'at' h:mm:ss a z" />
        </tstamp>
</target>

Notice that I created my own property called doc_build.time_stamp.

Usage

I use my new doc build timestamp property inside the target that I created for building the HTML docs.

<property name="javadoc.footer" value="&lt;strong&gt;Built:&lt;/strong&gt;&#09;${doc_build.time_stamp}." />

build.xml

build.xml is the default name used by Ant for the Ant project file.

My build.xml

Here’s the XML in my build.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<project name="3rdParty Mobile SDK" default="HTML Docs" basedir=".">

        <property name="src.dir"        value="${basedir}/src"/>
        <property name="dest.dir"       value="${basedir}/doc"/>
        <property name="lib.dir"        value="${basedir}/lib"/>

        <path id="classpath">
                <fileset dir="${lib.dir}" includes="**/*.jar"/>
        </path>

        <target name="init" description="Ant build project setup.">
                <tstamp>
                        <format property="doc_build.time_stamp" pattern="EEEE MMMM dd, yyyy 'at' h:mm:ss a z" />
                </tstamp>
        </target>

        <target name="HTML Docs" depends="init" description="Compile the HTML version of the docs.">
                <property name="javadoc.header" value="&lt;strong&gt;3rdParty Mobile SDK&lt;/strong&gt;&#09;v1.0" />
                <property name="javadoc.footer" value="&lt;strong&gt;Built:&lt;/strong&gt;&#09;${doc_build.time_stamp}." />
                <property name="javadoc.bottom" value='Copyright &amp;copy; 2013 - &lt;script&gt; var currYear=new Date(); document.write(currYear.getFullYear()); &lt;/script&gt;, 3rdParty Corp., All rights reserved.' />

                <javadoc
                  classpath="${basedir}/libs/android-support-v4.jar;C:\Android\sdk\platforms\android-19\android.jar"
                  access="public"
                  additionalparam=" -noqualifier java.lang:java.io "
                  author="true"
                  destdir="${dest.dir}"
                  doctitle="3rdParty Mobile SDK Documentation"
                  windowtitle="3rdParty Mobile SDK for Android"
                  nodeprecated="true"
                  nodeprecatedlist="true"
                  noindex="false"
                  nonavbar="false"
                  notree="false"
                  overview="${basedir}/overview.html"
                  packagenames="com.3rdPartymobilesdk"
                  source="7"
                  sourcepath="${src.dir}"
                  splitindex="true"
                  use="true"
                  version="true">
                        <link href="http://download.oracle.com/javase/7/docs/api/"/>
                        <header><![CDATA[${javadoc.header}]]></header>
                        <footer><![CDATA[${javadoc.footer}]]></footer>
                        <bottom><![CDATA[${javadoc.bottom}]]></bottom>
                </javadoc>

        </target>

</project>
Categories
Java

JavaDoc Generation

 

In Eclipse, run the Generate Javadoc command (Project > Generate Javadoc).

When you run the Javadoc Generator in Eclipse, a Wizard walks you through setting-up the job.

The Wizard consists of three pages.

Online Docs for the Javadoc Wizard

Javadoc Generator Settings

Note: I recommend that you use Eclipse’ Javadoc generator (Project > Generate Javadocs), and enable the option for it to automatically create a build.xml ant build file. Then open that build file in EditPad Pro, and customize it to your needs. See the build file in the java_3rdParty project for a prototype example.

%JDK_HOME%\bin\javadoc.exe

Note: JDK_HOME = C:Program FilesJavajdk1.7.0_21

Make sure the Windows Environment Variable PATH contains the directory that contains the javadoc.exe executable file (i.e., %JDK_HOME%bin).

This expands to: C:Program FilesJavajdk1.7.0_21binjavadoc.exe

Note: This won’t expand in the Generate Javadoc dialog box, but you can click Configure, and get the path to expand (%JAVA_HOME%\bin\).

Uncheck, and then re-check “src”. This ensures that every subpackage is checked (just one subpackage is checked by default).

Each option (Private, Packatge, Protected, and Public) is a superset of the options to its right. So select Private, and you get Package, Protected, and Public.

I like this option because it’s nice to see explanations for the private helper methods.

Use this option to generate the default doc style.

Destination: C:\Users\Chris\src\java_3rdParty\doc

Choose this option to generate docs using a different document generation algorithm. For example, you can specify a doclet that generates the docs in PDF form.

See the doclets available for download.

JELDoclet is a doclet that exports the contents of the Javadoc system as XML instead of HTML.

** See if you can create as XSLT with oXygen XML Editor, to generate a custom version of the docs.

Check this option.

I used the title: 3rdParty Java SDK Documentation

I checked all of the options, except @deprecated.

When you set this up properly, it makes your docs more user friendly, I turns all of the data types in your docs into hyperlinks to the external Javadocs for each particular referenced API.

Ideally, you want all of these checked. For the ones that are unchecked (and are labelled “not configured”), search the Internet for the name of the jar. One of the hits will contain the URL for the Javadocs generated for the API. Enter that URL, minus the terminating html file, into the Browse dialog, and click Validate. If it validates successfully, then click OK, and then check the check box beside the archive item.

See: http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#linkoffline

Javadoc relies on a file called package-list to identify the location of Javadocs – beneath a given directory. For some reason, such a file is missing for http://developer.android.com/reference. Therefore the “approach -link http://developer.android.com/reference doesn’t work (you get a warning that the package-list could not be retrieved and no links are generated into your docs). Note that the checkboxes in that 2nd eclipse dialog just assemble -link parameters for you, so that doesn’t really make any difference.

However, Javadoc offers the -linkoffline parameter as a workaround for this situation. It allows you to link to online Javadoc documentation, that you can’t access at the time of generating your own docs. Here’s how it works: While -link takes only one parameter (the URL of the JavaDoc docs you want to link to), -linkoffline takes a second one – the location of the package-list file.

So, to link to the online Android reference documentation, you should not select any checkboxes in the 2nd eclipse dialog, but instead add

-linkoffline http://developer.android.com/reference/ file://C:/opt/android-sdks/docs/reference

in the Extra Javadoc options in the 3rd dialog.

That way you use the package-list of your locally installed Android docs, but the links in your generated Javadoc will actually point to the online version.

I guess this must be where you can apply your custom stylesheet to the docs.

Experiment with this. Try opening the docset in Dreamweaver, and then adding your own style sheet on top of the default one.

Check the Overview checkbox.

Use the path: C:\Users\Chris\src\java_3rdParty\overview.html

As far as I can tell, you can leave this field blank.

-noqualifier java.lang:java.io
This truncates the full path names of the io members, leaving just the class name (like the using statemenmt in C#).

1.7

** When you use this option, the settings are stored in an Ant script named javadoc.xml, that you can resuse to perform the specified Javadoc export without the need to use the wizard.

Existing Ant script can be modified with this wizard (Use Open Javadoc wizard’ from the context menu on the generated Ant script)

Ant Script: C:\Users\Chris\src\java_3rdParty\javadoc.xml

  1. In Eclipse, Window > Open View > Other > Ant.
  2. Drag & drop the Ant build file from the Project Explorer into this Ant View pane.
  3. In the Ant view pane, double-click the target script.
  1. In Eclipse, in the Project Explorer, right-click the Ant build file (build.xml or javadoc.xml).
  2. Click Open in…
  3. Select the XML Editor.

This gives you two views into the Ant script.

 

Ant Script

<?xml version=”1.0″ encoding=”UTF-8″?>

<!– For info about what these attributes mean, see: http://ant.apache.org/manual/Tasks/javadoc.html –>

<project name=”3rdParty SDK for Android” default=”HTML Docs” basedir=”.”>

<property name=”src.dir” value=”${basedir}/src”/>

<property name=”dest.dir” value=”${basedir}/doc”/>

<property name=”lib.dir” value=”${basedir}/lib”/>

<path id=:classpath”>

<fileset dir=”${lib.dir}” includes=”

**

/

*

.jar”/></dd
</path>

<target name=”init” description=”Ant build project setup.”>
<tstamp>
<format property=”doc_build.time_stamp” pattern=”EEEE MMMM dd, yyyy ‘at’ h:mm:ss a z” />

</tstamp>

</target>

<target name=”HTML Docs” depends=”init” description=”Compile the HTML version of the docs.”>

<property name=”javadoc.header” value=”&lt;strong&gt;3rdParty SDK for Android&lt;/strong&gt;&#09;v1.0” /> <property name=”javadoc.footer” value=”&lt;strong&gt;Last updated on:&lt;/strong&gt;&#09;${doc_build.time_stamp}.” /> <property name=”javadoc.bottom” value=’Copyright &amp;copy; 2013 – &lt;script&gt; var currYear=new Date(); document.write(currYear.getFullYear()); &lt;/script&gt;, 3rdParty Corp., All rights reserved.’ />

<javadoc
classpath=”C:Androidsdkplatformsandroid-19android.jar;C:Androidsdkextrasandroidsupportv7appcompatlibsandroid-support-v4.jar”

access=”public” additionalparam=”-bootclasspath C:Androidsdkplatformsandroid-19android.jar -noqualifier java.lang:java.io” author=”true” destdir=”${dest.dir}” doctitle=”3rdParty SDK for Android” windowtitle=”3rdParty SDK for Android” nodeprecated=”true” nodeprecatedlist=”true” noindex=”false” nonavbar=”false” notree=”false” overview=”${basedir}/overview.html” packagenames=”com.3rdParty.sdk” source=”7” sourcepath=”${src.dir}” splitindex=”true” use=”true” version=”true”>

<link href=”http://download.oracle.com/javase/7/docs/api/“/> <link offline=”true” href=”http://developer.android.com/reference/” packagelistloc=”C:/Android/sdk/docs/reference”/> <header><![CDATA[${javadoc.header}]]></header> <footer><![CDATA[${javadoc.footer}]]></footer> <bottom><![CDATA[${javadoc.bottom}]]></bottom>

</javadoc>

</target>

</project>

Check this checkbox to see the doc web page in its own window inside Eclipse.

If you already have a browser instance open – displaying the docs from the last export, then don’t check this checkbox. Simply refresh the page displayed in the browser.

 

First-time Generation of the Docs

  1. In Eclipse, click Project > Generate Javadoc. Run Javadoc using the defaults for Destination: “C:\Users\Chris\src\java_3rdParty\doc”.
  • Javadoc command: ;%JDK_HOME%\bin\javadoc.exe.
  • For the types for which Javadoc will be generated, check everything under “src”. I.e., deselect everyting under “test”.

Customizing the Docs

The Javadoc tool generates output originating from four different types of source files:

Java language source files for classes Package comment files Overview comment files Miscellaneous unprocessed files

Sample Javadoc comment block

/** 3rdParty Java SDK
 * This Java package wraps the 3rdParty web service.
 * @package    PID.java
 * @author     cboorman
 * @copyright  Copyright © 2020, 3rdParty Corporation.
 * @license    http://opensource.org/licenses/mit-license.php The MIT License (MIT).
 * @version    1.0
 * @maintainer Git Administrator
 * @link       https://github.com/3rdParty/java_3rdParty
 * @email      Support <support@3rdParty.com>
 */