[OWASP-ESAPI] Current ESAPI-2.0rc3 Javadoc status

[Jim Manico]

> 1) Different titles on overview:
> GC> Title is "OWASP Enterprise Security API (ESAPI)"
> KWW> Title is "ESAPI 2.0 (quality branch)"


The title is something you choose during the Eclipse-Export-Javadoc wizard.

I chose "OWASP Enterprise Security API (ESAPI) 2.0 rc3" as the Javadoc 
title - make sure you see that title when you hit 
http://owasp-esapi-java.googlecode.com/svn/trunk_doc/index.html - the old 
version might still be cached in your browser.(ctrl-refresh should fix 
that).

> GC> Javadoc that Jim created and was put up on Google Code yesterday under 
> ... Then some trailing matter with ESAPI
>     architecture silo diagram and OWASP Top 10 coverage chart.

If you still see that ESAPI image at 
http://owasp-esapi-java.googlecode.com/svn/trunk_doc/index.html  Kevin - 
then you are looking at the old cached version. Can you ctrl-refresh and see 
if that fixes the other problems?

BTW: At any time, I might completely delete everything from 
http://owasp-esapi-java.googlecode.com/svn/trunk_doc/* and regenerate the 
Javadoc. If you want to make any changes to the Javadoc in svn, make the 
change in the code and ask me to regenerate the Javadoc. Fair?

- Jim

----- Original Message ----- 
From: "Kevin W. Wall" <kevin.w.wall at gmail.com>
To: "Jim Manico" <jim.manico at owasp.org>; "owasp-esapi" 
<owasp-esapi at lists.owasp.org>
Sent: Sunday, November 08, 2009 6:35 PM
Subject: Current ESAPI-2.0rc3 Javadoc status


> Jim,
>
> I have many things fixed, but there are still some things that I can't
> figure out where they are coming from. (Maybe someone on the list can
> figure it out.)
>
> For short-hand, I'm going to use notations 'GC>' & 'KWW>' to refer to:
>
> GC> Javadoc that Jim created and was put up on Google Code yesterday under
> http://owasp-esapi-java.googlecode.com/svn/trunk_doc/index.html
>
> KWW> The Javadoc that I generated from Eclipse via 
> File-->Export-->Javadoc.
>     I built the Javadoc under the default directory that the Eclipse 
> Javadoc
>     wizard defaults to, which is the 'doc' directory. (This is how Jim 
> told
>     me he had generated it.)
>
> Here are the things I still do not understand for certain why they
> are different:
> 1) Different titles on overview:
> GC> Title is "OWASP Enterprise Security API (ESAPI)"
> KWW> Title is "ESAPI 2.0 (quality branch)"
> ============
> 2) Different structure on overview summary page:
> GC> Lists title, then "See Description", then Packages table lists
>     6 packages, then repeats again, but this time Packages table
>     slightly different... 7 packages (added org.owasp.esapi.http) and
>     this time packages org.owasp.esapi.codecs and org.owasp.esapi.tags
>     have no package description. Then some trailing matter with ESAPI
>     architecture silo diagram and OWASP Top 10 coverage chart.
> KWW> No description or diagrams of any kind. Has 16 packages listed
>     in the table with package description missing for all of the new
>     ones.
>
> I speculate what is happening is that when you build the Javadoc it is 
> finding
> the overview-summary under 'svn/trunk/javadoc 
> resources/overview-summary.html'.
> Looks like it was generated last year by JDK 1.4 back on 9/15/2008 and 
> committed
> by Dave Wichers on 10/31/2008. So *IF* you are choosing 'javadoc 
> resources' as
> the directory for Eclipse to use to place your javadoc in, that *might* 
> account
> for these two things.  That only explains part of of it though. There is 
> NOWHERE
> under under a freshly checked out ESAPI 2.0rc3 source tree that has the 
> term
> "quality branch" in in ANYWHERE. So have no idea where THAT is coming 
> from.
>
> ============
> 3) Likewise other classes seem to be missing the image when I generate it. 
> E.g.,
> for org/owasp/esapi/Encryptor.html:
> GC> Includes fancy diagram called "Basic Encryptor". HTML source shows
> <img src="doc-files/Encryptor.jpg">
> KWW> Generated version shows same image file, but there is NO
>      'Encryptor.jpg' anywhere in the checked out SVN trunk.
> ============
> 4) Missing images apply to may other org.owasp.esapi classes as well.
>   So.. where did the JPG images go? Note that some of them are missing
>   completely (such as Encryptor.jpg), but others are there but just are
>   not showing up in the generated Javadoc. (E.g., 
> doc-files/Authenticator.jpg)
>   I'm starting to think this is a problem with Eclipse and/or ant.
> ============
> 5) The JUnit tests are still being included. I can probably solve that 
> problem,
>   but just haven't tried to hard on that one.
> ============
> 6) Started with about 300+ Javadoc warnings. I've probably fixed maybe 50 
> or
>   so, but at least 250 or so remaining.
> ============
>
> I think I'm going to commit the Javadoc changes that I have made in case 
> others
> wish to make actual code changes in those files.
>
> -kevin
> -- 
> Kevin W. Wall
> "The most likely way for the world to be destroyed, most experts agree,
> is by accident. That's where we come in; we're computer professionals.
> We cause accidents."        -- Nathaniel Borenstein, co-creator of MIME
>
>