blob: 7d860040f2642acc290af27e6745f9ac883ec9f4 [file] [log] [blame]
lmandelfe13d292005-07-11 19:53:21 +00001
3Each API package is required to have a package overview document describing
4at a high level the problem solved by the API, how the API is meant to be used,
5and where applicable diagrams and images explaining the expected and correct
8Like the design of the WTP website, the package overviews are stored as
9XML files within the root of the package that they describe. The file
10name must always be "package.xml". The XSLT stylesheet that runs as part
11of the Javadoc process will transform this file into a "package.html" file,
12which is expected by the javadoc tool.
14Developers have four tags to be aware of, in addition to the normal
15tag redefinitions that occur for the website (e.g. some header tags
16are redefined as white text with light blue backgrounds that span
17the page, like the Eclipse style). These four tags are:
19<p> tag: Each paragraph tag will be wrapped in a table that forces
20a fixed width for the text lines. Overviews that choose to add images
21can often stretch the text out into a width that is difficult or at a
22minimum inconvenient to read. Each <p> tag will be formatted consistently
23across all overview documents. Please refrain from adding extra formatting
24around paragraph tags.
26<img src="" caption=""> tag: Each image will be displayed in a specialized table format, with
27a caption. The <img> tag has an attribute "caption" that will be displayed
28just under the image explaining in text what the picture intends to
29convey graphically. For example:
31<img src=".." caption="This sample text" />
34| |
35| img |
39*Also note that all images used in a package overview must be placed in the
40root of the project under a directory named "javadoc-images". Whenever an
41image is linked to, the link must escape to the root package level
42to reference the image, and include "overview" in the path. So if you want to
43link "model_overview.jpg" into package overview for "com.acme.model":
45(1) Place "model_overview.jpg" in <project>\javadoc-images
46(2) Add the following element to your document:
47 <img src="../../../overview/model_overview.jpg" caption="An overview of the Acme Model API" />
48 --> Note that the three "../" escapes is the same number of elements in the
49 package path: com/acme/model/.
50 --> "overview/" is required as all images will be pushed into the "overview"
51 directory in the final javadoc layout.
54<codesnippet caption=""> tag: The codesnippet is provided to allow quick addition of code
55snippet examples or usage patterns for API. The content of the <codesnippet />
56tag should be the actual source code. The tag will use the text exactly as it
57appears in an HTML <pre> tag, and will wrap the snippet in a table for formatting.
58The codesnippet tag allows for a caption just as the img tag does.
60<abstract> tag: The abstract tag should always occur first in your content, and should
61contain a brief synopsis of your package overview ("package overview overview"). The
62contents of this tag will be displayed in the full API overview page beside the linked
63package name. The tag should contain no extra HTML formatting.