Skip to content

Commit

Permalink
Scaladoc: Groups
Browse files Browse the repository at this point in the history 
Group class members based on their semantic relationship. To do this:
 - @group on members, only need to do it for the non-overridden members
 - -groups flag passes to scaladoc, groups="on" in ant
 - @groupdesc Group Group Description to add descriptions
 - @groupName Group New name for group
 - @groupprio Group <int> (lower is better)
See test/scaladoc/run/groups.scala for a top-to-bottom example
  • Loading branch information
@VladUreche
VladUreche committed Jul 19, 2012
1 parent 0018f9b commit 0d367d4
Show file tree
Hide file tree
Showing 16 changed files with 436 additions and 67 deletions.
37 changes: 22 additions & 15 deletions build.xml
View file
Expand Up @@ -2044,7 +2044,7 @@ BOOTSTRAPPING BUILD (STRAP)
LIBRARIES (Forkjoin, FJBG, ASM)
============================================================================ -->


<target name="libs.clean" depends="pack.clean, asm.clean">
<delete dir="${build-libs.dir}" includeemptydirs="yes" quiet="yes" failonerror="no"/>
</target>
Expand Down Expand Up @@ -2112,9 +2112,10 @@ DOCUMENTATION
classpathref="pack.classpath"
addparams="${scalac.args.all}"
docRootContent="${src.dir}/library/rootdoc.txt"
implicits="on"
diagrams="on"
rawOutput="${scaladoc.raw.output}"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<src>
<files includes="${src.dir}/actors-migration"/>
Expand Down Expand Up @@ -2199,8 +2200,9 @@ DOCUMENTATION
srcdir="${src.dir}/compiler"
docRootContent="${src.dir}/compiler/rootdoc.txt"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand All @@ -2224,8 +2226,9 @@ DOCUMENTATION
classpathref="pack.classpath"
srcdir="${src.dir}/jline/src/main/java"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand All @@ -2252,7 +2255,8 @@ DOCUMENTATION
srcdir="${src.dir}/scalap"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand All @@ -2276,8 +2280,9 @@ DOCUMENTATION
classpathref="pack.classpath"
srcdir="${src.dir}/partest"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand All @@ -2301,8 +2306,9 @@ DOCUMENTATION
classpathref="pack.classpath"
srcdir="${src.dir}/continuations/plugin"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand All @@ -2326,8 +2332,9 @@ DOCUMENTATION
classpathref="pack.classpath"
srcdir="${src.dir}/actors-migration"
addparams="${scalac.args.all}"
implicits="on"
diagrams="on"
implicits="on"
diagrams="on"
groups="on"
rawOutput="${scaladoc.raw.output}"
noPrefixes="${scaladoc.no.prefixes}">
<include name="**/*.scala"/>
Expand Down
8 changes: 8 additions & 0 deletions src/compiler/scala/tools/ant/Scaladoc.scala
View file
Expand Up @@ -156,6 +156,9 @@ class Scaladoc extends ScalaMatchingTask {
/** Instruct the scaladoc not to generate prefixes */
private var docNoPrefixes: Boolean = false

/** Instruct the scaladoc tool to group similar functions together */
private var docGroups: Boolean = false

/*============================================================================*\
** Properties setters **
\*============================================================================*/
Expand Down Expand Up @@ -435,6 +438,10 @@ class Scaladoc extends ScalaMatchingTask {
def setNoPrefixes(input: String) =
docNoPrefixes = Flag.getBooleanValue(input, "noPrefixes")

/** Instruct the scaladoc tool to group similar functions together */
def setGroups(input: String) =
docGroups = Flag.getBooleanValue(input, "groups")

/*============================================================================*\
** Properties getters **
\*============================================================================*/
Expand Down Expand Up @@ -634,6 +641,7 @@ class Scaladoc extends ScalaMatchingTask {
docSettings.docDiagramsDebug.value = docDiagramsDebug
docSettings.docRawOutput.value = docRawOutput
docSettings.docNoPrefixes.value = docNoPrefixes
docSettings.docGroups.value = docGroups
if(!docDiagramsDotPath.isEmpty) docSettings.docDiagramsDotPath.value = docDiagramsDotPath.get

if (!docgenerator.isEmpty) docSettings.docgenerator.value = docgenerator.get
Expand Down
23 changes: 14 additions & 9 deletions src/compiler/scala/tools/nsc/ast/DocComments.scala
View file
Expand Up @@ -171,15 +171,15 @@ trait DocComments { self: Global =>
* 3. If there is no @return section in `dst` but there is one in `src`, copy it.
*/
def merge(src: String, dst: String, sym: Symbol, copyFirstPara: Boolean = false): String = {
val srcSections = tagIndex(src)
val dstSections = tagIndex(dst)
val srcParams = paramDocs(src, "@param", srcSections)
val dstParams = paramDocs(dst, "@param", dstSections)
val srcTParams = paramDocs(src, "@tparam", srcSections)
val dstTParams = paramDocs(dst, "@tparam", dstSections)
val out = new StringBuilder
var copied = 0
var tocopy = startTag(dst, dstSections dropWhile (!isMovable(dst, _)))
val srcSections = tagIndex(src)
val dstSections = tagIndex(dst)
val srcParams = paramDocs(src, "@param", srcSections)
val dstParams = paramDocs(dst, "@param", dstSections)
val srcTParams = paramDocs(src, "@tparam", srcSections)
val dstTParams = paramDocs(dst, "@tparam", dstSections)
val out = new StringBuilder
var copied = 0
var tocopy = startTag(dst, dstSections dropWhile (!isMovable(dst, _)))

if (copyFirstPara) {
val eop = // end of comment body (first para), which is delimited by blank line, or tag, or end of comment
Expand Down Expand Up @@ -209,6 +209,11 @@ trait DocComments { self: Global =>
for (tparam <- sym.typeParams)
mergeSection(srcTParams get tparam.name.toString, dstTParams get tparam.name.toString)
mergeSection(returnDoc(src, srcSections), returnDoc(dst, dstSections))
if (sym.name.toString == "isEmpty") {
println(groupDoc(src, srcSections))
println(groupDoc(dst, dstSections))
}
mergeSection(groupDoc(src, srcSections), groupDoc(dst, dstSections))

if (out.length == 0) dst
else {
Expand Down
7 changes: 6 additions & 1 deletion src/compiler/scala/tools/nsc/doc/Settings.scala
View file
Expand Up @@ -188,6 +188,11 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
"Expand all type aliases and abstract types into full template pages. (locally this can be done with the @template annotation)"
)

val docGroups = BooleanSetting (
"-groups",
"Group similar functions together (based on the @group annotation)"
)

// Somewhere slightly before r18708 scaladoc stopped building unless the
// self-type check was suppressed. I hijacked the slotted-for-removal-anyway
// suppress-vt-warnings option and renamed it for this purpose.
Expand All @@ -201,7 +206,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
docImplicits, docImplicitsDebug, docImplicitsShowAll,
docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses,
docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages,
docExpandAllTypes
docExpandAllTypes, docGroups
)
val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name)

Expand Down
42 changes: 39 additions & 3 deletions src/compiler/scala/tools/nsc/doc/html/page/Template.scala
View file
Expand Up @@ -110,10 +110,26 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp

<div id="mbrsel">
<div id='textfilter'><span class='pre'/><span class='input'><input id='mbrsel-input' type='text' accesskey='/'/></span><span class='post'/></div>
{ if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty) NodeSeq.Empty else
{ if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty && (!universe.settings.docGroups.value || (tpl.members.map(_.group).distinct.length == 1)))
NodeSeq.Empty
else
<div id="order">
<span class="filtertype">Ordering</span>
<ol><li class="alpha in"><span>Alphabetic</span></li><li class="inherit out"><span>By inheritance</span></li></ol>
<ol>
{
if (!universe.settings.docGroups.value || (tpl.members.map(_.group).distinct.length == 1))
NodeSeq.Empty
else
<li class="group out"><span>Grouped</span></li>
}
<li class="alpha in"><span>Alphabetic</span></li>
{
if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty)
NodeSeq.Empty
else
<li class="inherit out"><span>By inheritance</span></li>
}
</ol>
</div>
}
{ if (tpl.linearizationTemplates.isEmpty && tpl.conversions.isEmpty) NodeSeq.Empty else
Expand Down Expand Up @@ -223,6 +239,25 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp
}
</div>

<div id="groupedMembers">
{
val allGroups = tpl.members.map(_.group).distinct
val orderedGroups = allGroups.map(group => (tpl.groupPriority(group), group)).sorted.map(_._2)
// linearization
NodeSeq fromSeq (for (group <- orderedGroups) yield
<div class="group" name={ group }>
<h3>{ tpl.groupName(group) }</h3>
{
tpl.groupDescription(group) match {
case Some(body) => <div class="comment cmt">{ bodyToHtml(body) }</div>
case _ => NodeSeq.Empty
}
}
</div>
)
}
</div>

</div>

<div id="tooltip" ></div>
Expand All @@ -242,7 +277,8 @@ class Template(universe: doc.Universe, generator: DiagramGenerator, tpl: DocTemp
val memberComment = memberToCommentHtml(mbr, inTpl, false)
<li name={ mbr.definitionName } visbl={ if (mbr.visibility.isProtected) "prt" else "pub" }
data-isabs={ mbr.isAbstract.toString }
fullComment={ if(memberComment.filter(_.label=="div").isEmpty) "no" else "yes" }>
fullComment={ if(memberComment.filter(_.label=="div").isEmpty) "no" else "yes" }
group={ mbr.group }>
<a id={ mbr.signature }/>
{ signature(mbr, false) }
{ memberComment }
Expand Down
25 changes: 25 additions & 0 deletions src/compiler/scala/tools/nsc/doc/html/resource/lib/template.css
View file
Expand Up @@ -253,6 +253,17 @@ dl.attributes > dd {
color: white;
}

#groupedMembers > div.group > h3 {
background: #dadada url("typebg.gif") repeat-x bottom left; /* green */
height: 17px;
font-size: 12pt;
}

#groupedMembers > div.group > h3 * {
color: white;
}


/* Member cells */

div.members > ol {
Expand Down Expand Up @@ -516,6 +527,20 @@ div.members > ol > li:last-child {

/* Comments structured layout */

.group > div.comment {
padding-top: 5px;
padding-bottom: 5px;
padding-right: 5px;
padding-left: 5px;
border: 1px solid #ddd;
background-color: #eeeee;
margin-top:5px;
margin-bottom:5px;
margin-right:5px;
margin-left:5px;
display: block;
}

p.comment {
display: block;
margin-left: 14.7em;
Expand Down

0 comments on commit 0d367d4

Please sign in to comment.