1
/* NSC -- new Scala compiler
2
* Copyright 2007-2013 LAMP/EPFL
3
* @author Manohar Jonnalagedda
6
package scala.tools.nsc
11
import scala.collection._
13
/** A Scaladoc comment and all its tags.
15
* '''Note:''' the only instantiation site of this class is in [[CommentFactory]].
17
* @author Manohar Jonnalagedda
18
* @author Gilles Dubochet */
19
abstract class Comment {
21
/** The main body of the comment that describes what the entity does and is. */
24
private def closeHtmlTags(inline: Inline) = {
25
val stack = mutable.ListBuffer.empty[HtmlTag]
30
case tag: HtmlTag => {
31
if (stack.length > 0 && tag.canClose(stack.last)) {
32
stack.remove(stack.length-1)
47
Chain(List(inline) ++ stack.reverse)
50
/** A shorter version of the body. Usually, this is the first sentence of the body. */
60
/** A list of authors. The empty list is used when no author is defined. */
61
def authors: List[Body]
63
/** A list of other resources to see, including links to other entities or
64
* to external documentation. The empty list is used when no other resource
68
/** A description of the result of the entity. Typically, this provides additional
69
* information on the domain of the result, contractual post-conditions, etc. */
70
def result: Option[Body]
72
/** A map of exceptions that the entity can throw when accessed, and a
73
* description of what they mean. */
74
def throws: Map[String, Body]
76
/** A map of value parameters, and a description of what they are. Typically,
77
* this provides additional information on the domain of the parameters,
78
* contractual pre-conditions, etc. */
79
def valueParams: Map[String, Body]
81
/** A map of type parameters, and a description of what they are. Typically,
82
* this provides additional information on the domain of the parameters. */
83
def typeParams: Map[String, Body]
85
/** The version number of the entity. There is no formatting or further
86
* meaning attached to this value. */
87
def version: Option[Body]
89
/** A version number of a containing entity where this member-entity was introduced. */
90
def since: Option[Body]
92
/** An annotation as to expected changes on this entity. */
95
/** Whether the entity is deprecated. Using the `@deprecated` Scala attribute
96
* is prefereable to using this Scaladoc tag. */
97
def deprecated: Option[Body]
99
/** An additional note concerning the contract of the entity. */
102
/** A usage example related to the entity. */
103
def example: List[Body]
105
/** The comment as it appears in the source text. */
106
def source: Option[String]
108
/** A description for the primary constructor */
109
def constructor: Option[Body]
111
/** A set of diagram directives for the inheritance diagram */
112
def inheritDiagram: List[String]
114
/** A set of diagram directives for the content diagram */
115
def contentDiagram: List[String]
117
/** The group this member is part of */
118
def group: Option[String]
120
/** Member group descriptions */
121
def groupDesc: Map[String,Body]
123
/** Member group names (overriding the short tag) */
124
def groupNames: Map[String,String]
126
/** Member group priorities */
127
def groupPrio: Map[String,Int]
129
override def toString =
130
body.toString + "\n" +
131
(authors map ("@author " + _.toString)).mkString("\n") +
132
(result map ("@return " + _.toString)).mkString("\n") +
133
(version map ("@version " + _.toString)).mkString