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 java.util.*;
029
030import javax.lang.model.element.Element;
031import javax.lang.model.element.TypeElement;
032
033import com.sun.source.doctree.DocTree;
034
035/**
036 * The interface for writing member summary output.
037 */
038public interface MemberSummaryWriter {
039
040    /**
041     * Returns the member summary header for the given class.
042     *
043     * @param typeElement the class the summary belongs to
044     * @param content     the content to which the member summary will be added
045     *
046     * @return the member summary header
047     */
048    Content getMemberSummaryHeader(TypeElement typeElement, Content content);
049
050    /**
051     * Returns the summary table for the given class.
052     *
053     * @param typeElement the class the summary table belongs to
054     *
055     * @return the summary table
056     */
057    Content getSummaryTable(TypeElement typeElement);
058
059    /**
060     * Adds the member summary for the given class and member.
061     *
062     * @param typeElement        the class the summary belongs to
063     * @param member             the member that is documented
064     * @param firstSentenceTrees the tags for the sentence being documented
065     */
066    void addMemberSummary(TypeElement typeElement, Element member,
067            List<? extends DocTree> firstSentenceTrees);
068
069    /**
070     * Returns the inherited member summary header for the given class.
071     *
072     * @param typeElement the class the summary belongs to
073     *
074     * @return the inherited member summary header
075     */
076    Content getInheritedSummaryHeader(TypeElement typeElement);
077
078    /**
079     * Adds the inherited member summary for the given class and member.
080     *
081     * @param typeElement the class the inherited member belongs to
082     * @param member the inherited member that is being documented
083     * @param isFirst true if this is the first member in the list
084     * @param isLast true if this is the last member in the list
085     * @param content the content to which the links will be added
086     */
087    void addInheritedMemberSummary(TypeElement typeElement,
088            Element member, boolean isFirst, boolean isLast,
089            Content content);
090
091    /**
092     * Returns the inherited summary links.
093     *
094     * @return the inherited summary links
095     */
096    Content getInheritedSummaryLinks();
097
098    /**
099     * Adds the given summary to the list of summaries.
100     *
101     * @param summariesList the list of summaries
102     * @param content       the summary
103     */
104    void addSummary(Content summariesList, Content content);
105
106    /**
107     * Returns the member content.
108     *
109     * @param memberContent the content representing the member
110     *
111     * @return the member content
112     */
113    Content getMember(Content memberContent);
114}