<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" ><generator uri="https://jekyllrb.com/" version="4.3.4">Jekyll</generator><link href="http://egonw.github.io/blog/feed/by_tag/javadoc.xml" rel="self" type="application/atom+xml" /><link href="http://egonw.github.io/blog/" rel="alternate" type="text/html" /><updated>2026-11-19T06:09:00+00:00</updated><id>http://egonw.github.io/blog/feed/by_tag/javadoc.xml</id><title type="html">chem-bla-ics</title><subtitle>Chemblaics (pronounced chem-bla-ics) is the science that uses open science and computers to solve problems in chemistry, biochemistry and related fields.</subtitle><author><name>Egon Willighagen</name></author><entry><title type="html">Cleaner CDK Code #4: inheriting JavaDoc from super classes and interfaces</title><link href="http://egonw.github.io/blog/2010/03/30/cleaner-cdk-code-4-inheriting-javadoc.html" rel="alternate" type="text/html" title="Cleaner CDK Code #4: inheriting JavaDoc from super classes and interfaces" /><published>2010-03-30T00:00:00+00:00</published><updated>2010-03-30T00:00:00+00:00</updated><id>http://egonw.github.io/blog/2010/03/30/cleaner-cdk-code-4-inheriting-javadoc</id><content type="html" xml:base="http://egonw.github.io/blog/2010/03/30/cleaner-cdk-code-4-inheriting-javadoc.html"><![CDATA[<p>When you write a class implementing an interface or extending a super class, it is often the case that the API is
identical. It would be nice to inherit the JavaDoc documentation, which is possible.</p>

<h2 id="inheriting-javadoc">Inheriting JavaDoc</h2>
<p>Java method that overwrite a superclass method or implement an interface method, can inherit JavaDoc by including this JavaDoc for that method:</p>

<div class="language-java highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/** {@inheritDoc} */</span>
<span class="nd">@TestMethod</span><span class="o">(</span><span class="s">"testGetMIMEType"</span><span class="o">)</span>
<span class="kd">public</span> <span class="nc">String</span> <span class="nf">getMIMEType</span><span class="o">()</span> <span class="o">{</span>
  <span class="k">return</span> <span class="kc">null</span><span class="o">;</span>
<span class="o">}</span>
</code></pre></div></div>

<p>The JavaDoc documentation <a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#inheritingcomments">notes</a> that
missing @param and @return values are inherited implicitly since JavaDoc 1.3, but I have never noticed this in Java6. The
above <em>explicit</em> markup is confirmed to work.</p>]]></content><author><name>Egon Willighagen</name></author><category term="cdk" /><category term="java" /><category term="javadoc" /><summary type="html"><![CDATA[When you write a class implementing an interface or extending a super class, it is often the case that the API is identical. It would be nice to inherit the JavaDoc documentation, which is possible.]]></summary></entry><entry><title type="html">Call for Collaboration: JavaDoc validation with OpenJavaDocCheck</title><link href="http://egonw.github.io/blog/2009/11/07/call-for-collaboration-javadoc.html" rel="alternate" type="text/html" title="Call for Collaboration: JavaDoc validation with OpenJavaDocCheck" /><published>2009-11-07T00:00:00+00:00</published><updated>2009-11-07T00:00:00+00:00</updated><id>http://egonw.github.io/blog/2009/11/07/call-for-collaboration-javadoc</id><content type="html" xml:base="http://egonw.github.io/blog/2009/11/07/call-for-collaboration-javadoc.html"><![CDATA[<p>I reported recently about my efforts to write an <a href="http://chem-bla-ics.blogspot.com/2009/10/work-in-progress-open-doccheck.html">Open Source DocCheck replacement</a>.
I received the first patches (from <a href="http://blog.rguha.net/">Rajarshi</a>), and brought it online in a <a href="http://cdk.sf.net/">CDK</a> branch (see
<a href="http://pele.farmbio.uu.se/nightly-ojdcheck/ojdcheckSummary.html">this Nightly page</a>).</p>

<p><img src="/blog/assets/images/ojdcheck.png" alt="" /></p>

<p>This list shows a mix of tests that are now implemented in OpenJavaDocCheck itself, but the third line is actually a test that is plugged in and specific for the CDK. This is an important feature, I think, and allows users of OpenJavaDocCheck to add functionality is that is not interesting to the general public, but very interesting for the JavaDoc being analyzed. Well, at least, it is to our CDK project :)</p>

<p>The current list of tests is still quite small, and consists of these tests:</p>

<ul>
  <li>test if each class and method has JavaDoc</li>
  <li>test for missing @return tags</li>
  <li>test for missing @param tags</li>
  <li>test for @returns instead of @return</li>
  <li>test @param template code, such as added by IDEs like Eclipse</li>
  <li>test @exception template code, such as added by IDEs like Eclipse</li>
  <li>test for redundant @version tags</li>
</ul>

<p>I am now <a href="http://github.com/egonw/ojdcheck/issues">seeking feedback</a> on the current code base, and potentially collaboration with writing more
JavaDoc validation tests. There is enough to do, and I have been thinking on tests for:</p>

<ul>
  <li>spell checking JavaDoc</li>
  <li>checking for 404s of web pages linked with <code class="language-plaintext highlighter-rouge">&lt;a href&gt;</code> in the JavaDoc</li>
  <li>well-formedness of the HTML in the webpages</li>
</ul>

<p>And about:</p>

<ul>
  <li>a PMD-like system to allow people to choose which testing they want or not</li>
  <li>an Eclipse plugin</li>
</ul>]]></content><author><name>Egon Willighagen</name></author><category term="cdk" /><category term="javadoc" /><summary type="html"><![CDATA[I reported recently about my efforts to write an Open Source DocCheck replacement. I received the first patches (from Rajarshi), and brought it online in a CDK branch (see this Nightly page).]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="http://egonw.github.io/blog/blog/assets/images/ojdcheck.png" /><media:content medium="image" url="http://egonw.github.io/blog/blog/assets/images/ojdcheck.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Work in Progress: an Open DocCheck replacement</title><link href="http://egonw.github.io/blog/2009/10/17/work-in-progress-open-doccheck.html" rel="alternate" type="text/html" title="Work in Progress: an Open DocCheck replacement" /><published>2009-10-17T00:00:00+00:00</published><updated>2009-10-17T00:00:00+00:00</updated><id>http://egonw.github.io/blog/2009/10/17/work-in-progress-open-doccheck</id><content type="html" xml:base="http://egonw.github.io/blog/2009/10/17/work-in-progress-open-doccheck.html"><![CDATA[<p>While it is still very much in progress, I have already made more progress than I had hoped for. The <a href="http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/doclet/spec/index.html">JavaDoc Doclet API</a>
is actually not too difficult to use, though my use will very likely improve more later. The <a href="http://cdk.sf.net/">CDK</a> has been using
<a href="http://java.sun.com/j2se/javadoc/doccheck/">Sun’s DocCheck</a> utility for testing the library’s JavaDoc quality, but the reports never
really satisfied me. Moreover, the most recent version is ancient and because it is <em>closed source</em>, no one can continue on those efforts.
DocCheck is <a href="http://en.wikipedia.org/wiki/Missing_In_Action">MIA</a>.</p>

<p>Instead, <a href="http://pmd.sf.net/">PMD</a> is given nice overviews of what it believes to be wrong with the CDK, and also provides a decent XML
format which allows extraction of information, which is used by, for example, <a href="http://pele.farmbio.uu.se/supernightly/">SuperNightly</a> as
showed yesterday in <a href="http://chem-bla-ics.blogspot.com/2009/10/pmd-245-installed-in-cdk-12x-branch.html">PMD 2.4.5 installed in the CDK 1.2.x branch</a>.</p>

<p>I have been pondering about it for a long time now, but writing a JavaDoc checking library is hardly core cheminformatics research;
at least, you would not get funding for it, despite everyone always complaining about good documentation. <em>Alas</em>.</p>

<p>Last week, I was reviewing some more code, and again saw the very common error of the missing period at the end of the first sentence
in JavaDoc. This one is sort of important for proper JavaDoc documentation generation, but the complexity of the current DocCheck
reporting, people are not familiar enough with it. Being tired of having to repeat myself, I decided to address the problen, but
creating better <a href="http://pele.farmbio.uu.se/nightly/javadoc/data/">Nightly error reporting for the CDK JavaDoc</a>.</p>

<p>So, I started <a href="http://github.com/egonw/ojdcheck">OpenJavaDocCheck</a>, or <em>ojdcheck</em>. As mentioned, I have made quite promising progress,
and the current version provides the ability to write custom tests (which I plan to use for validating content of
<a href="http://cdk.sourceforge.net/guides/devel/ch01.html">CDK taglet</a> content), and create XML as well as XHTML which can be saved to any file.
To give you a glimps of where things are going, here’s a screenshot of the current XHTML output:</p>

<p><img src="/blog/assets/images/ojdcheckXHTML.png" alt="" /></p>

<p>The current list of tests is really small, and consists of a single test:</p>

<ul>
  <li>test if each class and method has JavaDoc</li>
</ul>]]></content><author><name>Egon Willighagen</name></author><category term="cdk" /><category term="javadoc" /><category term="java" /><category term="xml" /><summary type="html"><![CDATA[While it is still very much in progress, I have already made more progress than I had hoped for. The JavaDoc Doclet API is actually not too difficult to use, though my use will very likely improve more later. The CDK has been using Sun’s DocCheck utility for testing the library’s JavaDoc quality, but the reports never really satisfied me. Moreover, the most recent version is ancient and because it is closed source, no one can continue on those efforts. DocCheck is MIA.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="http://egonw.github.io/blog/blog/assets/images/ojdcheckXHTML.png" /><media:content medium="image" url="http://egonw.github.io/blog/blog/assets/images/ojdcheckXHTML.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry><entry><title type="html">Pimp my JavaDoc</title><link href="http://egonw.github.io/blog/2007/02/19/pimp-my-javadoc.html" rel="alternate" type="text/html" title="Pimp my JavaDoc" /><published>2007-02-19T00:00:00+00:00</published><updated>2007-02-19T00:00:00+00:00</updated><id>http://egonw.github.io/blog/2007/02/19/pimp-my-javadoc</id><content type="html" xml:base="http://egonw.github.io/blog/2007/02/19/pimp-my-javadoc.html"><![CDATA[<p><a href="http://miningdrugs.blogspot.com/">Jörg</a>’s PhD book <em>Data Mining und Graph Mining auf molekularen Graphen - Chemoinformatik und
molekulare Kodierungen für ADME/Tox-QSAR-Analysen</em> has a dump of the JavaDoc of the <code class="language-plaintext highlighter-rouge">GroupContributionPredictor</code> in
<a href="http://joelib.sf.net/">JOELib</a> (Figure 3.2, page 43). There are two nice things to the shown JavaDoc: 1. it has links to
<a href="http://www.wikipedia.org/">Wikipedia</a>; 2. it has a Further Reading section.</p>

<p>Now, the <a href="http://cdk.sf.net/">CDK</a> already links to a bibliography for some time now. However, it would just give a BibTex
key, and link to a webpage created from a <a href="http://bibtexml.sf.net/">BibTeXML</a> file in which we store all references
(<a href="http://cdk.svn.sourceforge.net/viewvc/cdk/trunk/cdk/doc/refs/cheminf.bibx?view=log">cdk/doc/refs/cheminf.bibx</a>).
Putting the full citation inline makes the JavaDoc more informative, but I wanted to preserve the <code class="language-plaintext highlighter-rouge">@cdk.cite</code>
mechanism we were using.</p>

<p>This weekend I hacked up a nice CDKCiteDoclet that would read the BibTeXML file with <a href="http://www.xom.nu/">XOM</a>,
and convert items to HTML to put into the pimped JavaDoc:</p>

<p><img src="/blog/assets/images/pimpedJavaDoc.png" alt="" /></p>]]></content><author><name>Egon Willighagen</name></author><category term="cdk" /><category term="javadoc" /><category term="literature" /><summary type="html"><![CDATA[Jörg’s PhD book Data Mining und Graph Mining auf molekularen Graphen - Chemoinformatik und molekulare Kodierungen für ADME/Tox-QSAR-Analysen has a dump of the JavaDoc of the GroupContributionPredictor in JOELib (Figure 3.2, page 43). There are two nice things to the shown JavaDoc: 1. it has links to Wikipedia; 2. it has a Further Reading section.]]></summary><media:thumbnail xmlns:media="http://search.yahoo.com/mrss/" url="http://egonw.github.io/blog/blog/assets/images/pimpedJavaDoc.png" /><media:content medium="image" url="http://egonw.github.io/blog/blog/assets/images/pimpedJavaDoc.png" xmlns:media="http://search.yahoo.com/mrss/" /></entry></feed>