001/*
002 * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package org.jdrupes.mdoclet.internal.doclets.toolkit;
027
028import javax.lang.model.element.TypeElement;
029
030import org.jdrupes.mdoclet.internal.doclets.toolkit.util.DocFileIOException;
031
032/**
033 * The interface for writing class output.
034 */
035public interface ClassWriter {
036
037    /**
038     * Get the header of the page.
039     *
040     * @param header the header string to write
041     * @return header content that needs to be added to the documentation
042     */
043    Content getHeader(String header);
044
045    /**
046     * Get the class content header.
047     *
048     * @return class content header that needs to be added to the documentation
049     */
050    Content getClassContentHeader();
051
052    /**
053     * Add the class inheritance tree documentation.
054     *
055     * @param target the content to which the documentation will be added
056     */
057    void addClassTree(Content target);
058
059    /**
060     * Add the type parameter and state component information.
061     *
062     * @param target the content to which the documentation will be added
063     */
064    void addParamInfo(Content target);
065
066    /**
067     * Add all superinterfaces if this is an interface.
068     *
069     * @param target the content to which the documentation will be added
070     */
071    void addSuperInterfacesInfo(Content target);
072
073    /**
074     * Add all implemented interfaces if this is a class.
075     *
076     * @param target the content to which the documentation will be added
077     */
078    void addImplementedInterfacesInfo(Content target);
079
080    /**
081     * Add all the classes that extend this one.
082     *
083     * @param target the content to which the documentation will be added
084     */
085    void addSubClassInfo(Content target);
086
087    /**
088     * Add all the interfaces that extend this one.
089     *
090     * @param target the content to which the documentation will be added
091     */
092    void addSubInterfacesInfo(Content target);
093
094    /**
095     * If this is an interface, add all classes that implement this
096     * interface.
097     *
098     * @param target the content to which the documentation will be added
099     */
100    void addInterfaceUsageInfo(Content target);
101
102    /**
103     * If this is an functional interface, display appropriate message.
104     *
105     * @param target the content to which the documentation will be added
106     */
107    void addFunctionalInterfaceInfo(Content target);
108
109    /**
110     * If this is an inner class or interface, add the enclosing class or
111     * interface.
112     *
113     * @param target the content to which the documentation will be added
114     */
115    void addNestedClassInfo(Content target);
116
117    /**
118     * {@return the class information}
119     *
120     * @param classInfo the class information
121     */
122    Content getClassInfo(Content classInfo);
123
124    /**
125     * If this class is deprecated, add the appropriate information.
126     *
127     * @param classInfo the content to which the documentation will be added
128     */
129    void addClassDeprecationInfo(Content classInfo);
130
131    /**
132     * Add the signature of the current class content.
133     *
134     * @param classInfo the class content to which the signature will be added
135     */
136    void addClassSignature(Content classInfo);
137
138    /**
139     * Build the class description.
140     *
141     * @param classInfo the content to which the documentation will be added
142     */
143    void addClassDescription(Content classInfo);
144
145    /**
146     * Add the tag information for the current class.
147     *
148     * @param classInfo the content to which the tag information will be added
149     */
150    void addClassTagInfo(Content classInfo);
151
152    /**
153     * Returns a list to be used for the list of summaries for members of a given kind.
154     *
155     * @return a list to be used for the list of summaries for members of a given kind
156     */
157    Content getSummariesList();
158
159    /**
160     * Returns an item for the list of summaries for members of a given kind.
161     *
162     * @param content content for the item
163     * @return an item for the list of summaries for members of a given kind
164     */
165    Content getSummariesListItem(Content content);
166
167    /**
168     * Returns a list to be used for the list of details for members of a given kind.
169     *
170     * @return a list to be used for the list of details for members of a given kind
171     */
172    Content getDetailsList();
173
174    /**
175     * Returns an item for the list of details for members of a given kind.
176     *
177     * @param content content for the item
178     * @return an item for the list of details for members of a given kind
179     */
180    Content getDetailsListItem(Content content);
181
182    /**
183     * Add the class content.
184     *
185     * @param classContent the class content which will be added to the content
186     */
187    void addClassContent(Content classContent);
188
189    /**
190     * Add the footer of the page.
191     */
192    void addFooter();
193
194    /**
195     * Print the document.
196     *
197     * @param content the content that will be printed as a document
198     * @throws DocFileIOException if there is a problem while writing the document
199     */
200    void printDocument(Content content) throws DocFileIOException;
201
202    /**
203     * Return the TypeElement being documented.
204     *
205     * @return the TypeElement being documented.
206     */
207    TypeElement getTypeElement();
208
209    /**
210     * {@return the member summary}
211     *
212     * @param memberContent the content used to build the summary
213     */
214    Content getMemberSummary(Content memberContent);
215
216    /**
217     * {@return the member details}
218     *
219     * @param memberContent the content used to generate the member details
220     */
221    Content getMemberDetails(Content memberContent);
222}