View Javadoc
1   package org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  /**
23   * <p>Specification for how to convert/render JavaDocData into an XML annotation. As an example, let us
24   * assume that a class contains the following field and JavaDoc:</p>
25   * <pre>
26   *     <code>
27   *         {@literal /}**
28   *         The last name of the SomewhatNamedPerson.
29   *         *{@literal /}
30   *         {@literal @}XmlElement(nillable = false, required = true)
31   *         private String lastName;
32   *     </code>
33   * </pre>
34   * <p>The standard SchemaGen generation creates a complex type with the following element declaration:</p>
35   * <pre>
36   *     <code>
37   *         &lt;xs:element name="lastName" type="xs:string" /&gt;
38   *     </code>
39   * </pre>
40   * <p>However, if we use the jaxb2-maven-plugin for post-processing, we can inject the javadoc as an XSD
41   * annotation into the resulting schema, yielding the following result:</p>
42   * <pre>
43   *     <code>
44   *         &lt;xs:element name="lastName" type="xs:string"&gt;
45   *             &lt;xs:annotation&gt;
46   *                 &lt;xs:documentation&gt;&lt;![CDATA[The last name of the SomewhatNamedPerson.]]&gt;&lt;/xs:documentation&gt;
47   *             &lt;/xs:annotation&gt;
48   *         &lt;/xs:element&gt;
49   *     </code>
50   * </pre>
51   * <p>The JavaDocRenderer will create the content of the CDATA element within the XSD documentation annotation,
52   * given the JavaDocData for each field, such as the <em>lastName</em> in our example.</p>
53   *
54   * @author <a href="mailto:lj@jguru.se">Lennart J&ouml;relid</a>, jGuru Europe AB
55   * @see org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc.DefaultJavaDocRenderer
56   * @since 2.0
57   */
58  public interface JavaDocRenderer {
59  
60      /**
61       * <p>Renders the supplied JavaDocData structure as text to be used within an XSD documentation annotation.
62       * The XSD documentation annotation will contain a CDATA section to which the rendered JavaDocData is
63       * emitted.</p>
64       *
65       * @param nonNullData the JavaDocData instance to render as XSD documentation. Will never be {@code null}.
66       * @param location    the SortableLocation where the JavaDocData was harvested. Never {@code null}.
67       * @return The rendered text contained within the XML annotation.
68       */
69      String render(JavaDocData nonNullData, SortableLocation location);
70  }