Re: Enhancing SystemML JavaDocs

[Niketan Pansare <np...@us.ibm.com>]

Since we also now have Python APIs, it might be a good idea to consider
hosting them too along with javadocs. Here is a link to our current
documentation:
https://htmlpreview.github.io/?https://github.com/apache/incubator-systemml/blob/master/docs/devdocs/python_api.html

This documentation can be generated using following steps:
$ cd src/main/python
$ sphinx-apidoc --full --force --output-dir docs systemml
$ cd docs

Add following lines to conf.py
import sys
sys.path.append('...FULL PATH...src/main/python/')
autodoc_mock_imports = ['pyspark', 'py4j.java_gateway',
'pyspark.mllib.common', 'pyspark.context', 'pyspark.sql', 'pyspark.ml',
'pyspark.ml.feature']

$ make singlehtml

As an FYI, Spark moved to Sphinx in version 1.2.0 (please see SPARK-3420).

Thanks,

Niketan Pansare
IBM Almaden Research Center
E-mail: npansar At us.ibm.com
http://researcher.watson.ibm.com/researcher/view.php?person=us-npansar



From:	Frederick R Reiss/Almaden/IBM@IBMUS
To:	dev@systemml.incubator.apache.org
Date:	09/30/2016 04:33 PM
Subject:	Re: Enhancing SystemML JavaDocs



Wow, I was not aware that those empty JavaDocs were put in -- and left in
-- on purpose! To me they are the epitome of useless comments. At best they
convey exactly the same information as the line of code immediately below
them. Much of the time they end up conveying an incorrect, out-of-date
version of the same. And all of the time they limit the amount of useful
code that can be on screen at once. Are there many people on the project
who actually like the current JavaDoc policy?

Fred

Luciano Resende ---09/30/2016 03:18:41 PM---On Fri, Sep 30, 2016 at 1:42
PM, Deron Eriksson <de...@gmail.com> wrote:

From: Luciano Resende <lu...@gmail.com>
To: dev@systemml.incubator.apache.org
Date: 09/30/2016 03:18 PM
Subject: Re: Enhancing SystemML JavaDocs



On Fri, Sep 30, 2016 at 1:42 PM, Deron Eriksson <de...@gmail.com>
wrote:

> I do not see how these automatically generated javadocs are useful. For
> instance:
>
> /**
> *
> * @param pb
> * @param ec
> * @return
> * @throws DMLRuntimeException
> */
> public static double getTimeEstimate(ProgramBlock pb, ExecutionContext
ec,
> boolean recursive)
> throws DMLRuntimeException
>
> Here, someone has automatically generated a javadoc comment. The
developer
> has failed to correct the missing 'recursive' parameter. If a developer
has
> not created a blank javadoc comment in the first place, then the
recursive
> parameter mistake never would have been made because there never would
have
> been a blank javadoc comment to update in the first place.
>
> If automatically generated javadoc comments are decided to be part of our
> coding standard, then they should be applied to all methods, not just
> random methods.
>
> Deron
>
>

Completely agree Deron, these are becoming stale and obsolete with the APIs
being enhanced and the javadocs being left behind. In the past I actually
tried to fix some, but as you mentioned there is a lot and we need a
community effort here.

Another approach is to make javadocs update MANDATORY for PR acceptance,
meaning that, if you touch a given file, you fix any javadoc related to
that file.

Thoughts ?


--
Luciano Resende
http://twitter.com/lresende1975
http://lresende.blogspot.com/