[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-build-dev
Subject:    Re: Provide zipped javadoc archive from make
From:       Jiri Vanek <jvanek () redhat ! com>
Date:       2016-02-29 15:24:03
Message-ID: 56D46293.3020102 () redhat ! com
[Download RAW message or body]

On 02/26/2016 08:05 PM, Jonathan Gibbons wrote:
> On 02/26/2016 03:49 AM, Jiri Vanek wrote:
> > On 02/25/2016 06:34 PM, Jonathan Gibbons wrote:
> > > On 02/25/2016 09:23 AM, Jiri Vanek wrote:
> > > > 
> > > > I must be missing something. Dozens? Of varius runs of javadoc?
> > > > 
> > > > I thought that javadoc ending at the end in single drectory is one single \
> > > > javadoc for java. If you are referring to javadoc generated by "per module" \
> > > > then one jjoined zip is enough for me.
> > > 
> > > 
> > > Jiri,
> > > 
> > > If you accept the premise  that javadoc writes one stylesheet.css file per run \
> > > of javadoc, take a look at the following list:
> > 
> > Then my goal will be to crate a trget, which takes
> > build/linux-x86_64-normal-server-release/images/docs/
> > and pack it to
> > build/linux-x86_64-normal-server-release/images/javadoc.zip
> > 
> > It should contains also the "smaller api" you are mentioning below? If not, then \
> > those should appear in this zip too.
> > > 
> > > $ find build/linux-x86_64-normal-server-release/images/docs/ -name \
> > > stylesheet.css \
> > > build/linux-x86_64-normal-server-release/images/docs/jdk/api/dynalink/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/attach/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/javac/tree/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/jconsole/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/jpda/jdi/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/doclet/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/doclet/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/javadoc/old/taglet/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jdk/api/nashorn/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/api/stylesheet.css
> > > build/linux-x86_64-normal-server-release/images/docs/jre/api/nio/sctp/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/plugin/dom/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jaas/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/security/smartcardio/spec/stylesheet.css
> > >  
> > > build/linux-x86_64-normal-server-release/images/docs/jre/api/security/jgss/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/management/extension/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/net/httpserver/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/net/socketoptions/spec/stylesheet.css
> > >  build/linux-x86_64-normal-server-release/images/docs/jre/api/accessibility/jaccess/spec/stylesheet.css
> > >  
> > > 
> > > The "main"/"Java SE" javadoc bundle that most are aware of is the shortest \
> > > filename, in the middle of the list, but there are lots of other smaller APIs \
> > > that get their own doc bundle.  You can get at most of them in released doc \
> > > sets through the top-level "brick wall" page, or by using your favorite search \
> > > engine.
> > 
> > Hmm.. Do you have some?  javadoc offline search is quite painful think. (Even \
> > with new search in 9, which seems to have some troubles on local filesystem). The \
> > best search engine I know is (unluckily) \
> > https://github.com/judovana/JavadocOfflineSearch
> 
> The point of the preceding list was to say that each directory containing \
> stylesheet.css is the root of a separate, distinct, javadoc bundle.  So the smaller \
> APIs that get their own bundle are precisely the ones given in the preceding list, \
> other than the main javadoc bundle. 
> The point of the comment about the brick wall and search engines was to indicate \
> how most people will find these doc bundles in normal use, when they don't have a \
> cheat sheet like the list above.

yes I got that. But Then this compressed shattered javadoc needs more thoughts.

What is expected format of distribution?
I can imagine: web accessible, unapcked "all docs" and "zipepd "all docs".
But never several zips, or several directories.

What is what I'm missing behind this effort to deliver javadocs per-module?

> 
> As far as IDEs wanting to access javadoc bundles, I would expect that to make all \
> the docs available, you would want to zip up *each* directory containing \
> stylesheet.css given in the preceding list. If you just zip up the top API \
> directory, sure, that will include all the files, but the reality is that the IDE \
> will likely not have any way of knowing about the minor doc bundles in all jre/ and \
> jdk/ directories and subdirectories.

Indeed, when you pack top level javadoc directroy as top level of archive (so javadco \
will become  zipped1.zip!javadoc) then indeed, Netbeasn refuse to load it whole 9just \
few parts)

However when you pack it  that content of javadoc will be the top of the archive 
(zipped2.zip!{api,jdk,jre,platform}) then NB loads it fine.

If even this is wrong, then as last approach is really to restructuralise docs after \
theirs  generation/before zipping to structure where top level directory will the \
"one with style"

dynalink/stylesheet.css
spec/stylesheet.css
tree/stylesheet.css
spec/stylesheet.css
jdi/stylesheet.css
doclet/stylesheet.css
nashorn/stylesheet.css
api/stylesheet.css
spec/stylesheet.css
dom/stylesheet.css
spec/stylesheet.css
spec/stylesheet.css
...

But looking to the occurences of "spec" There is something wrong with those \
assumptions :)


As for indexing and viewing tools - They works fine with both zipepd1 and zipped2 \
(but there is not  much to try)

Seeing the impact of packaging, I think it is one more +1 to add this packing target, \
so JDK's  javadoc is pacaked in known, "laodable" way.

Thanx!
   J.

> 
> -- Jon
> 
> 
> > > 
> > > --
> > 
> > 
> > Thanx a lot!
> > J.
> 


[prev in list] [next in list] [prev in thread] [next in thread]