This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 31344 - Publish architecture documents as part of javadoc
Summary: Publish architecture documents as part of javadoc
Alias: None
Product: platform
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 3.x
Hardware: All All
: P2 blocker (vote)
Assignee: Jesse Glick
Keywords: ARCH
Depends on:
Blocks: 30370
  Show dependency tree
Reported: 2003-02-21 17:22 UTC by Jaroslav Tulach
Modified: 2008-12-22 23:45 UTC (History)
1 user (show)

See Also:
Exception Reporter:


Note You need to log in before you can comment on or make changes to this bug.
Description Jaroslav Tulach 2003-02-21 17:22:52 UTC
Let's include the written arch documents into some
place in javadoc.
Comment 1 Jesse Glick 2003-02-21 20:42:06 UTC
So based on our conversation:

1. nbbuild/template.xml should support a param "javadoc.arch", value a
file location for an arch *.xml file. If this prop is defined, should
create a file ${javadoc.out}/arch.html based on running <arch> with
that input param.

2. For a module which is properly separated and has its own docs -
e.g. openide/compiler - it is the responsibility of the module to
include a link to arch.html somewhere appropriate in the
documentation. E.g. first paragraph of a doc-files/api.html.

2a. Note: currently template.xml does not support Javadoc overview
files, so you can't link to it from there; would be nice to solve
that, though it is hard to make the <javadoc> task include an overview
only conditionally. (Would need two copies of <javadoc> in
template.xml - ugly.) Maybe there could be a default overview page
used for any module which does not supply its own - it would have to
include links to arch.html if ${javadoc.arch} is specified, and/or a
link to ${} if that is specified. May just be easier
to make the overview file mandatory.

3. The openide main module is harder because currently it does not use
template.xml for <javadoc> - maybe it could, I don't know. Anyway that
has several arch.xml's associated with it. So for now, suggest that
openide/build.xml directly run <arch> and include the results in
openide/javadoc/OpenAPIs/*.html. openide/api/doc/overview.html would
of course need to link to all of them.

4. We could think about permitting @OPENIDE@ and similar tokens in the
arch *.xml documents, to make it easier for these to link to published
APIs. Note that this would mean that */arch/build.xml and whatever you
use to generate the final ARC case would need to do these replacements
- currently only nbbuild/template.xml (and openide/build.xml) knows
about them.
Comment 2 Jesse Glick 2003-02-25 20:22:47 UTC
I am working on rather similar changes for issue #29313 anyway, so I
think it will be easiest if I just do this together with those.
Comment 3 Jesse Glick 2003-02-26 06:13:26 UTC
Comment 4 Jaroslav Tulach 2003-07-14 15:32:28 UTC