Package org.jdrupes.mdoclet.internal.doclets.formats.html

Klasse HtmlDocletWriter

java.lang.Object
org.jdrupes.mdoclet.internal.doclets.formats.html.HtmlDocletWriter
Bekannte direkte Unterklassen:
AbstractOverviewIndexWriter, AbstractTreeWriter, AllClassesIndexWriter, AllPackagesIndexWriter, ConstantsSummaryWriterImpl, ExternalSpecsWriter, HelpWriter, IndexRedirectWriter, IndexWriter, ModuleWriterImpl, PackageWriterImpl, SearchWriter, SubWriterHolderWriter, SystemPropertiesWriter
public class HtmlDocletWriter extends Object
Class for the Html Format Code Generation specific to JavaDoc.

This Class contains methods related to the Html Code Generation which are used extensively while generating the entire documentation.

  • Felddetails

    • pathToRoot

      public final DocPath pathToRoot
      Relative path from the file getting generated to the destination directory.

      For example, if the file getting generated is “java/lang/Object.html”, then the path to the root is “../..”. This string can be empty if the file getting generated is in the destination directory.

    • path

      public final DocPath path
      Platform-independent path from the current or the destination directory to the file getting generated.

      Used when creating the file.

    • filename

      public final DocPath filename
      Name of the file getting generated.

      If the file getting generated is “java/lang/Object.html”, then the filename is “Object.html”.

    • configuration

      public final HtmlConfiguration configuration
      The global configuration information for this run.

    • options

      protected final HtmlOptions options

    • utils

      protected final Utils utils

    • contents

      protected final Contents contents

    • messages

      protected final Messages messages

    • resources

      protected final Resources resources

    • docPaths

      protected final DocPaths docPaths

    • comparators

      protected final Comparators comparators

    • htmlIds

      protected final HtmlIds htmlIds

    • winTitle

      protected String winTitle
      The window title of this file.

    • mainBodyScript

      protected Script mainBodyScript

  • Konstruktordetails

    • HtmlDocletWriter

      public HtmlDocletWriter(HtmlConfiguration configuration, DocPath path)
      Creates an HtmlDocletWriter.
      Parameter:
      configuration - the configuration for this doclet
      path - the file to be generated.

  • Methodendetails

    • replaceDocRootDir

      public String replaceDocRootDir(String htmlstr)
      Replace {@docRoot} tag used in options that accept HTML text, such as -header, -footer, -top and -bottom, and when converting a relative HREF where commentTagsToString inserts a {@docRoot} where one was missing.

      (Also see DocRootTaglet for {@docRoot} tags in doc comments.)

      Replace {@docRoot} tag in htmlstr with the relative path to the destination directory from the directory where the file is being written, looping to handle all such tags in htmlstr.

      For example, for "-d docs" and -header containing {@docRoot}, when the HTML page for source file p/C1.java is being generated, the {@docRoot} tag would be inserted into the header as "../", the relative path from docs/p/ to docs/ (the document root).

      Note: This doc comment was written with '@' representing '@' to prevent the inline tag from being interpreted.

    • addTagsInfo

      protected void addTagsInfo(Element e, Content content)
      Adds the tags information.
      Parameter:
      e - the Element for which the tags will be generated
      content - the content to which the tags will be added

    • getBlockTagOutput

      protected Content getBlockTagOutput(Element element)
      Returns the content generated from the default supported set of block tags for this element.
      Parameter:
      element - the element
      Gibt zurück:
      the content

    • getBlockTagOutput

      protected Content getBlockTagOutput(Element element, List<Taglet> taglets)
      Returns the content generated from a specified set of block tags for this element.
      Parameter:
      element - the element
      taglets - the taglets to handle the required set of tags
      Gibt zurück:
      the content

    • hasSerializationOverviewTags

      protected boolean hasSerializationOverviewTags(VariableElement field)
      Returns whether there are any tags in a field for the Serialization Overview section to be generated.
      Parameter:
      field - the field to check
      Gibt zurück:
      true if and only if there are tags to be included

    • getTagletWriterInstance

      public TagletWriter getTagletWriterInstance(boolean isFirstSentence)
      Returns a TagletWriter that knows how to write HTML.
      Parameter:
      isFirstSentence - true if we want to write the first sentence
      Gibt zurück:
      a TagletWriter that knows how to write HTML.

    • getTagletWriterInstance

      public TagletWriterImpl getTagletWriterInstance(org.jdrupes.mdoclet.internal.doclets.formats.html.TagletWriterImpl.Context context)
      Returns a TagletWriter that knows how to write HTML.
      Parameter:
      context - the enclosing context
      Gibt zurück:
      a TagletWriter

    • printHtmlDocument

      public void printHtmlDocument(List<String> metakeywords, String description, Content body) throws DocFileIOException
      Generates the HTML document tree and prints it out.
      Parameter:
      metakeywords - Array of String keywords for META tag. Each element of the array is assigned to a separate META tag. Pass in null for no array
      description - the content for the description META tag.
      body - the body htmltree to be included in the document
      Löst aus:
      DocFileIOException - if there is a problem writing the file

    • printHtmlDocument

      public void printHtmlDocument(List<String> metakeywords, String description, List<DocPath> localStylesheets, Content body) throws DocFileIOException
      Generates the HTML document tree and prints it out.
      Parameter:
      metakeywords - Array of String keywords for META tag. Each element of the array is assigned to a separate META tag. Pass in null for no array
      description - the content for the description META tag.
      localStylesheets - local stylesheets to be included in the HEAD element
      body - the body htmltree to be included in the document
      Löst aus:
      DocFileIOException - if there is a problem writing the file

    • printHtmlDocument

      public void printHtmlDocument(List<String> metakeywords, String description, Content extraHeadContent, List<DocPath> localStylesheets, Content body) throws DocFileIOException
      Generates the HTML document tree and prints it out.
      Parameter:
      metakeywords - Array of String keywords for META tag. Each element of the array is assigned to a separate META tag. Pass in null for no array
      description - the content for the description META tag.
      extraHeadContent - any additional content to be included in the HEAD element
      localStylesheets - local stylesheets to be included in the HEAD element
      body - the body htmltree to be included in the document
      Löst aus:
      DocFileIOException - if there is a problem writing the file

    • getWindowTitle

      public String getWindowTitle(String title)
      Get the window title.
      Parameter:
      title - the title string to construct the complete window title
      Gibt zurück:
      the window title string

    • getHeader

      protected HtmlTree getHeader(Navigation.PageMode pageMode)
      Returns a
      element, containing the user “top” text, if any, and the main navigation bar.
      Parameter:
      pageMode - the pageMode used to configure the navigation bar
      Gibt zurück:
      the
      element

    • getHeader

      protected HtmlTree getHeader(Navigation.PageMode pageMode, Element element)
      Returns a
      element, containing the user “top” text, if any, and the main navigation bar.
      Parameter:
      pageMode - the page mode used to configure the navigation bar
      element - the element used to configure the navigation bar
      Gibt zurück:
      the
      element

    • getNavBar

      protected Navigation getNavBar(Navigation.PageMode pageMode, Element element)
      Returns a basic navigation bar for a kind of page and element.
      Parameter:
      pageMode - the page mode
      element - the defining element for the navigation bar, or null if none
      Gibt zurück:
      the basic navigation bar

    • getFooter

      public HtmlTree getFooter()
      Returns a
      element containing the user’s “bottom” text, or null if there is no such text.
      Gibt zurück:
      the
      element or null.

    • getNavLinkToOverviewTree

      protected Content getNavLinkToOverviewTree(String label)
      Gibt an "overview tree" link for a navigation bar zurück.
      Parameter:
      label - the label for the link
      Gibt zurück:
      an "overview tree" link for a navigation bar

    • getLocalizedPackageName

      public Content getLocalizedPackageName(PackageElement packageElement)
      Gibt a package name zurück.

      A localized name is returned for an unnamed package. Use Utils.getPackageName(PackageElement) to get a static string for the unnamed package instead.

      Parameter:
      packageElement - the package to get the name for
      Gibt zurück:
      a package name

    • getPackageLabel

      public Content getPackageLabel(CharSequence packageName)
      Returns a package name label.
      Parameter:
      packageName - the package name
      Gibt zurück:
      the package name content

    • pathString

      protected DocPath pathString(TypeElement te, DocPath name)
      Return the path to the class page for a typeElement.
      Parameter:
      te - TypeElement for which the path is requested.
      name - Name of the file(doesn’t include path).

    • pathString

      protected DocPath pathString(PackageElement packageElement, DocPath name)
      Return path to the given file name in the given package.

      So if the name passed is “Object.html” and the name of the package is “java.lang”, and if the relative path is “../..” then returned string will be “../../java/lang/Object.html”

      Parameter:
      packageElement - Package in which the file name is assumed to be.
      name - File name, to which path string is.

    • getPackageLink

      public Content getPackageLink(PackageElement packageElement, Content label)
      Gibt the link to the given package zurück.
      Parameter:
      packageElement - the package to link to
      label - the label for the link
      Gibt zurück:
      the link to the given package

    • getPackageLink

      public Content getPackageLink(PackageElement packageElement, Content label, String fragment)
      Gibt the link to the given package zurück.
      Parameter:
      packageElement - the package to link to
      label - the label for the link
      fragment - the link fragment
      Gibt zurück:
      the link to the given package

    • getModuleLink

      public Content getModuleLink(ModuleElement mdle, Content label)
      Gibt a link to module zurück.
      Parameter:
      mdle - the module being documented
      label - tag for the link
      Gibt zurück:
      a link to module

    • getModuleLink

      public Content getModuleLink(ModuleElement mdle, Content label, String fragment)
      Gibt a link to module zurück.
      Parameter:
      mdle - the module being documented
      label - tag for the link
      fragment - the link fragment
      Gibt zurück:
      a link to module

    • addSrcLink

      public void addSrcLink(Element element, Content label, Content target)
      Add the link to the content.
      Parameter:
      element - program element for which the link will be added
      label - label for the link
      target - the content to which the link will be added

    • getLink

      public Content getLink(HtmlLinkInfo linkInfo)
      Return the link to the given class.
      Parameter:
      linkInfo - the information about the link.
      Gibt zurück:
      the link for the given class.

    • getTypeParameterLinks

      public Content getTypeParameterLinks(HtmlLinkInfo linkInfo)
      Return the type parameters for the given class.
      Parameter:
      linkInfo - the information about the link.
      Gibt zurück:
      the type for the given class.

    • getCrossClassLink

      public Content getCrossClassLink(TypeElement classElement, String refMemName, Content label, HtmlStyle style, boolean code)
      Return a class cross link to external class documentation.

      The -link option does not allow users to link to external classes in the “default” package.

      Parameter:
      classElement - the class element
      refMemName - the name of the member being referenced. This should be null or empty string if no member is being referenced.
      label - the label for the external link.
      style - optional style for the link.
      code - true if the label should be code font.
      Gibt zurück:
      the link

    • getCrossPackageLink

      public DocLink getCrossPackageLink(PackageElement element)

    • getCrossModuleLink

      public DocLink getCrossModuleLink(ModuleElement element)

    • getQualifiedClassLink

      public Content getQualifiedClassLink(HtmlLinkInfo.Kind context, Element element)
      Gibt a link to the given class zurück.
      Parameter:
      context - the id of the context where the link will be added
      element - the class to link to
      Gibt zurück:
      a link to the given class

    • addPreQualifiedClassLink

      public void addPreQualifiedClassLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Content target)
      Adds a link to the given class.
      Parameter:
      context - the id of the context where the link will be added
      typeElement - the class to link to
      target - the content to which the link will be added

    • getPreQualifiedClassLink

      public Content getPreQualifiedClassLink(HtmlLinkInfo.Kind context, TypeElement typeElement)
      Retrieve the class link with the package portion of the label in plain text.

      If the qualifier is excluded, it will not be included in the link label.

      Parameter:
      typeElement - the class to link to.
      Gibt zurück:
      the link with the package portion of the label in plain text.

    • addPreQualifiedClassLink

      public void addPreQualifiedClassLink(HtmlLinkInfo.Kind context, TypeElement typeElement, HtmlStyle style, Content target)
      Add the class link with the package portion of the label in plain text.

      If the qualifier is excluded, it will not be included in the link label.

      Parameter:
      context - the id of the context where the link will be added
      typeElement - the class to link to
      style - optional style for the link
      target - the content to which the link with be added

    • getEnclosingPackageName

      public String getEnclosingPackageName(TypeElement te)
      Get the enclosed name of the package
      Parameter:
      te - TypeElement
      Gibt zurück:
      the name

    • getCurrentPageElement

      protected TypeElement getCurrentPageElement()
      Return the main type element of the current page or null for pages that don’t have one.
      Gibt zurück:
      the type element of the current page.

    • addPreQualifiedStrongClassLink

      public void addPreQualifiedStrongClassLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Content content)
      Add the class link, with only class name as the strong link and prefixing plain package name.
      Parameter:
      context - the id of the context where the link will be added
      typeElement - the class to link to
      content - the content to which the link with be added

    • getDocLink

      public Content getDocLink(HtmlLinkInfo.Kind context, Element element, CharSequence label)
      Gibt a link to the given member zurück.
      Parameter:
      context - the id of the context where the link will be added
      element - the member being linked to
      label - the label for the link
      Gibt zurück:
      a link to the given member

    • getDocLink

      public Content getDocLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Element element, CharSequence label)
      Return the link for the given member.
      Parameter:
      context - the id of the context where the link will be printed.
      typeElement - the typeElement that we should link to. This is not necessarily the type containing element since we may be inheriting comments.
      element - the member being linked to.
      label - the label for the link.
      Gibt zurück:
      the link for the given member.

    • getDocLink

      public Content getDocLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Element element, CharSequence label, HtmlStyle style)
      Return the link for the given member.
      Parameter:
      context - the id of the context where the link will be printed.
      typeElement - the typeElement that we should link to. This is not necessarily the type containing element since we may be inheriting comments.
      element - the member being linked to.
      label - the label for the link.
      style - optional style for the link.
      Gibt zurück:
      the link for the given member.

    • getDocLink

      public Content getDocLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Element element, CharSequence label, boolean isProperty)
      Return the link for the given member.
      Parameter:
      context - the id of the context where the link will be printed.
      typeElement - the typeElement that we should link to. This is not necessarily the type containing element since we may be inheriting comments.
      element - the member being linked to.
      label - the label for the link.
      Gibt zurück:
      the link for the given member.

    • getDocLink

      public Content getDocLink(HtmlLinkInfo.Kind context, TypeElement typeElement, Element element, Content label, HtmlStyle style, boolean isProperty)
      Return the link for the given member.
      Parameter:
      context - the id of the context where the link will be printed.
      typeElement - the typeElement that we should link to. This is not necessarily the type containing element since we may be inheriting comments.
      element - the member being linked to.
      label - the label for the link.
      style - optional style to use for the link.
      isProperty - true if the element parameter is a JavaFX property.
      Gibt zurück:
      the link for the given member.

    • addInlineComment

      public void addInlineComment(Element element, DocTree tag, Content target)
      Add the inline comment.
      Parameter:
      element - the Element for which the inline comment will be added
      tag - the inline tag to be added
      target - the content to which the comment will be added

    • getDeprecatedPhrase

      public Content getDeprecatedPhrase(Element e)
      Gibt a phrase describing the type of deprecation zurück.
      Parameter:
      e - the Element for which the inline deprecated comment will be added
      Gibt zurück:
      a phrase describing the type of deprecation

    • addInlineDeprecatedComment

      public void addInlineDeprecatedComment(Element e, DeprecatedTree tag, Content target)
      Add the inline deprecated comment.
      Parameter:
      e - the Element for which the inline deprecated comment will be added
      tag - the inline tag to be added
      target - the content to which the comment will be added

    • addSummaryComment

      public void addSummaryComment(Element element, Content target)
      Adds the summary content.
      Parameter:
      element - the Element for which the summary will be generated
      target - the content to which the summary will be added

    • addPreviewComment

      public void addPreviewComment(Element element, List<? extends DocTree> firstSentenceTags, Content target)
      Adds the preview content.
      Parameter:
      element - the Element for which the summary will be generated
      firstSentenceTags - the first sentence tags for the doc
      target - the content to which the summary will be added

    • addSummaryComment

      public void addSummaryComment(Element element, List<? extends DocTree> firstSentenceTags, Content target)
      Adds the summary content.
      Parameter:
      element - the Element for which the summary will be generated
      firstSentenceTags - the first sentence tags for the doc
      target - the content to which the summary will be added

    • addSummaryDeprecatedComment

      public void addSummaryDeprecatedComment(Element element, DeprecatedTree tag, Content target)

    • addInlineComment

      public void addInlineComment(Element element, Content target)
      Adds the full-body content of the given element.
      Parameter:
      element - the element for which the content will be added
      target - the content to which the content will be added

    • commentTagsToContent

      public Content commentTagsToContent(Element element, List<? extends DocTree> tags, boolean isFirstSentence)
      Converts inline tags and text to content, expanding the inline tags along the way.

      Called wherever text can contain an inline tag, such as in comments or in free-form text arguments to block tags.

      Parameter:
      element - specific element where comment resides
      tags - list of text trees and inline tag trees (often alternating)
      isFirstSentence - true if text is first sentence
      Gibt zurück:
      a Content object

    • commentTagsToContent

      public Content commentTagsToContent(Element element, List<? extends DocTree> trees, boolean isFirstSentence, boolean inSummary)
      Converts inline tags and text to content, expanding the inline tags along the way.

      Called wherever text can contain an inline tag, such as in comments or in free-form text arguments to block tags.

      Parameter:
      element - specific element where comment resides
      trees - list of text trees and inline tag trees (often alternating)
      isFirstSentence - true if text is first sentence
      inSummary - if the comment tags are added into the summary section
      Gibt zurück:
      a Content object

    • commentTagsToContent

      public Content commentTagsToContent(Element element, List<? extends DocTree> trees, org.jdrupes.mdoclet.internal.doclets.formats.html.TagletWriterImpl.Context context)
      Converts inline tags and text to content, expanding the inline tags along the way.

      Called wherever text can contain an inline tag, such as in comments or in free-form text arguments to block tags.

      Parameter:
      element - specific element where comment resides
      trees - list of text trees and inline tag trees (often alternating)
      context - the enclosing context for the trees
      Gibt zurück:
      a Content object

    • invalidTagOutput

      protected Content invalidTagOutput(String summary, Optional<Content> detail)
      Returns the output for an invalid tag.

      The returned content uses special styling to highlight the problem. Depending on the presence of the detail string the method returns a plain text span or an expandable component.

      Parameter:
      summary - the single-line summary message
      detail - the optional detail message which may contain preformatted text
      Gibt zurück:
      the output

    • getAnnotations

      public List<Content> getAnnotations(List<? extends AnnotationMirror> descList, boolean lineBreak)
      Return the string representations of the annotation types for the given doc.
      Parameter:
      descList - a list of annotation mirrors.
      lineBreak - if true, add new line between each member value.
      Gibt zurück:
      a list of strings representing the annotations being documented.

    • getPackageTableHeader

      protected TableHeader getPackageTableHeader()

    • getBody

      public HtmlTree getBody(String title)
      Returns an HtmlTree for the BODY element.
      Parameter:
      title - title for the window
      Gibt zurück:
      an HtmlTree for the BODY tag

    • getBodyStyle

      public HtmlStyle getBodyStyle()

    • addPreviewSummary

      public void addPreviewSummary(Element forWhat, Content target)

    • addPreviewInfo

      public void addPreviewInfo(Element forWhat, Content target)

    • resolveExternalSpecURI

      public URI resolveExternalSpecURI(URI specURI)