1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74 | package Torello.JavaDoc;
import java.lang.annotation.*;
// @CSSLinks Annotation
//
// EXPORTS:
// public String[] FileNames();
//
// * Torello.JavaDoc.CSSLinks
// This is the actual User-Annotation that is part of the Upgrader-API. A user may place the
// @CSSLinks Annotation on a Type / CIET (Class, Interface, Enum, Annotation or
// Rec) - And a CSS-File Link in the form of a <LINK REL=stylesheet TYPE=text/css HREF=...>
// will be inserted for Class / Type / CIET that the user has annotated.
//
// * package Torello.JDUInternal.Features.USER_SUPPLIED_CSS_FILES
// The classes in this package do the processing for inserting the '.css' Files which the user
// has requested be placed into his Java-Doc '.html' Web-Page. These '.css' Files must be
// located in the '../upgrade-files/stylesheets/' directory. These '.css' Files must either:
//
// 1) obey the standard naming convention and have the exact same file-name as the
// Java-Class which has been annotated by the @CSSLinks Annotation
//
// 2) have a name equal to one of the names provided to the Annotation-Element "FileNames"
//
// * Torello.JDUInternal.Annotations.TypeAnnotations.Processor.CSSLinksProcessor
// This is the Annotation-Processsor that is / can-be invoked by the 'javac' (Java-Compiler) at
// Compile-Time. This Annotation-Processor does not do very much, but will check that the
// names provided to the "FileNames" Annotation-Element are, indeed, valid Operating-System
// File-Names - which exist and are accessible.
//
// * Torello.JDUInternal.Annotations.TypeAnnotations.Mirror.CSSLMirror
// After the JDU Detects that a CIET / Type has had the @CSSLinks Annotation placed upon
// it, this class extracts the relevant information out of the Annotation using the AST
// Library in 'com.sun.source.tree' and all of it's helper classes.
/**
* This Annotation allows a user to request that a CSS Link-Import be included in the Header
* Portion of any CIET/Type's respective Java-Doc Web-Page. This Annotation allows for multiple
* sheets to be applied to a single Java-Doc Page.
*
* <BR /><BR />The {@link #FileNames()} element in this annotation should be supplied with
* names for a file located inside the {@code ../upgrade-files/stylesheets/} sub-directory of
* whatever Java Source-Code Package in which your CIET/Type (your {@code '.java'} file) resides.
* When you specify a CSS-File in that directory, you need not include any actual directory string
* information in the file-name. Just the Simple-Name of the file itself is expected / sufficient.
*
* <BR /><BR />Importing CSS-Files from other locations on disk is also allowed. In such cases
* you would then (and only then) be obligated to include the Full-Path / Canonical File-Name
* for the CSS-File to be imported.
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.SOURCE)
@JDHeaderBackgroundImg()
public @interface CSSLinks
{
/**
* The CSS-StyleSheet file (or files) for which an HTML {@code <LINK REL=stylesheet>} Tag is to
* be inserted into this CIET/Type's Java-Doc Page Header.
*
* <BR /><BR />This Annotation-Element is a {@code String}-Array, which means more than one
* Style-Sheet may be included here. If the Style-Sheet has been properly placed, directly,
* into the {@code ../upgrade-files/stylesheets/} directory, then this {@code 'FileNames'}
* {@code String}-Array <I>should not include any parent or container directory information in
* the any of those kinds of FileName-{@code String's}</I>.
*
* <BR /><BR />If a StyleSheet whose location on disk is situated on the File-System in some
* unrelated place, then the file's Full-Path Name (or at least it's Relative-Path Name with
* respect to the Current Working Directory at Build Initiation Time) should be the
* {@code String} used within this Array-Element.
*/
public String[] FileNames();
}
|