<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!-- ===================================================================
     
     Apache JavaDoc DTD (version 0.4-draft)

PURPOSE:
  This DTD is designed to capture the output of JavaDoc as an XML document
  through the use of the JavaDocXML Doclet. The hope is that by having the
  JavaDoc documentation in an XML format, it will be easier for application
  developers working with XML to treat their java source documentation in the
  same way they treat any other XML document within their publication framework.
  
  This DTD should reflect the information contained within the RootDoc object 
  passed to the JavaDocXML Doclet by JavaDoc. The RootDoc object and the rest 
  of the javaDoc Doclet API is specified at
  
  http://java.sun.com/products/jdk/1.2/docs/tooldocs/javadoc/doclet/index.html
  
  The only information that appears to be difficult to derive from this DTD
  that is easy to obtain from the RootDoc object is the information about 
  serialization. However, this information should be derivable by manually 
  looking for the correct serialization methods and other related structures.
  
TYPICAL INVOCATION:

  <!DOCTYPE document PUBLIC
       "-//APACHE//DTD JavaDoc Vx.yz//EN"
       "javadoc-vxyz.dtd">

  where 
  
    x := major version
    y := minor version
    z := status identifier (optional)
      
NOTES:  
  The authors would like to thank the Cocoon's mail list subscribers for 
  providing such great support and feedback for this DTD.
  
FIXME:

CHANGE HISTORY:
  199909?? Original idea of XML doclet. (KM)
  199910?? Initial version of this DTD. (KM)
  19991129 Cleaned up DTD. (SM)
    
==================================================================== -->

<!-- =============================================================== -->
<!-- Common Attribute Entities -->
<!-- =============================================================== -->

<!ENTITY % name 'name CDATA #REQUIRED'>
<!ENTITY % dimension 'dimension CDATA #REQUIRED'>

<!ENTITY % abstract 'abstract (true | false) "false"'>
<!ENTITY % anonymous 'anonymous (true | false) "false"'>
<!ENTITY % synthetic 'synthetic (true | false) "false"'>
<!ENTITY % static 'static (true | false) "false"'>
<!ENTITY % final 'final (true | false) "false"'>
<!ENTITY % transient 'transient (true | false) "false"'>
<!ENTITY % volatile 'volatile (true | false) "false"'>
<!ENTITY % native 'native (true | false) "false"'>
<!ENTITY % synchronized 'synchronized (true | false) "false"'>

<!ENTITY % access 'access (private | package | protected | public) "package"'>
<!ENTITY % class.access 'access (package | public) "package"'>

<!ENTITY % extensibility 'extensibility (abstract | final | default) "default"'>


<!-- =============================================================== -->
<!-- Javadoc -->
<!-- =============================================================== -->

<!ELEMENT javadoc (package*, class*, interface*)>

<!-- =============================================================== -->
<!-- Package -->
<!-- =============================================================== -->

<!ELEMENT package (doc?, package*, class*, interface*)>
<!ATTLIST package %name;>

<!-- =============================================================== -->
<!-- Class -->
<!-- =============================================================== -->

<!ELEMENT class (doc?,
                 extends_class?,
                 implements?,
                 field*, 
                 constructor*, 
                 method*,
                 innerclass*)>
<!ATTLIST class
          %name;
          %extensibility;
          %class.access;>

<!ELEMENT extends_class (classref+)>
          
<!ELEMENT innerclass (doc?,
                      extends?,
                      implements?,
                      field*, 
                      constructor*, 
                      method*)>
<!ATTLIST innerclass
          %name;
          %access;
          %abstract;
          %anonymous;
          %final;
          %static;>
          
<!-- =============================================================== -->
<!-- Interface -->
<!-- =============================================================== -->
          
<!ELEMENT interface (doc?,
                     extends_interface?,
                     field*,
                     method*)>
<!ATTLIST interface
          %name;
          %access;>
          
<!ELEMENT extends_interface (interfaceref+)>

<!-- =============================================================== -->
<!-- Elements -->
<!-- =============================================================== -->

<!ELEMENT implements (interfaceref+)>

<!ELEMENT throws (classref)+>

<!ELEMENT classref EMPTY>
<!ATTLIST classref %name;>
          
<!ELEMENT interfaceref EMPTY>
<!ATTLIST interfaceref %name;>
          
<!ELEMENT methodref EMPTY>
<!ATTLIST methodref %name;>
          
<!ELEMENT packageref EMPTY>
<!ATTLIST packageref %name;>
          
<!ELEMENT primitive EMPTY>
<!ATTLIST primitive
          type (void | boolean | int | long | byte | short | double | float | char) #REQUIRED>
          
<!ELEMENT field (doc?, (classref | interfaceref | primitive))>
<!ATTLIST field
          %name;
          %access;
          %dimension;
          %synthetic;
          %static;
          %final;
          %transient;
          %volatile;>
          
<!ELEMENT constructor (doc?, parameter*, throws*)>
<!ATTLIST constructor
          %name;
          %access;
          %synthetic;>
          
<!ELEMENT method (doc?, returns, parameter*, throws*)>
<!ATTLIST method
          %name;
          %access;
          %extensibility;
          %native;
          %synthetic;
          %static;
          %synchronized;>
          
<!ELEMENT returns (classref | interfaceref | primitive)>
<!ATTLIST returns %dimension;>
          
<!ELEMENT parameter (classref | interfaceref | primitive)>
<!ATTLIST parameter
          %name;
          %final;
          %dimension;>
          
<!ELEMENT dimension (#PCDATA)>

<!ELEMENT doc (#PCDATA | 
               linktag |
               authortag |
               versiontag |
               paramtag |
               returntag |
               exceptiontag |
               throwstag |
               seetag |
               sincetag |
               deprecatedtag |
               serialtag |
               serialfieldtag |
               serialdatatag)*>
               
<!ELEMENT linktag (#PCDATA)>
<!ATTLIST linktag
          src CDATA #REQUIRED>
          
<!ELEMENT authortag (#PCDATA | linktag)*>

<!ELEMENT versiontag (#PCDATA | linktag)*>

<!ELEMENT paramtag (#PCDATA | linktag)*>
<!ATTLIST paramtag %name;>
          
<!ELEMENT returntag (#PCDATA | linktag)*>

<!ELEMENT exceptiontag (#PCDATA | classref | linktag)*>

<!ELEMENT throwstag (#PCDATA | classref | linktag)*>

<!ELEMENT seetag (#PCDATA | linktag)*>
<!ATTLIST seetag
          src CDATA #REQUIRED>
          
<!ELEMENT sincetag (#PCDATA | linktag)*>

<!ELEMENT deprecatedtag (#PCDATA | linktag)*>

<!ELEMENT serialtag (#PCDATA | linktag)*>

<!ELEMENT serialfieldtag (#PCDATA | linktag)*>
<!ATTLIST serialfieldtag
          fieldname CDATA #REQUIRED
          fieldtype CDATA #REQUIRED>
          
<!ELEMENT serialdatatag (#PCDATA | linktag)*>

<!-- =============================================================== -->
<!-- End of DTD -->
<!-- =============================================================== -->
