azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactored the comments to split the wiki markup into the first paragraph for the summary and the rest for the detail and to allow relative URL links to classes in wiki links

Browse Source
This commit is contained in:
James Strachan
2012-03-07 10:22:52 +00:00
parent a6254ec4aa
commit 585625bf2f
6 changed files with 65 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/kdoc/pom.xml
+4 -4
View File
@@ -6,9 +6,9 @@
<modelVersion>4.0.0</modelVersion> <modelVersion>4.0.0</modelVersion>
<parent> <parent>
<groupId>org.jetbrains.kotlin</groupId> <groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-project</artifactId> <artifactId>kotlin-project</artifactId>
<version>1.0-SNAPSHOT</version> <version>1.0-SNAPSHOT</version>
</parent> </parent>
<artifactId>kdoc</artifactId> <artifactId>kdoc</artifactId>
@@ -17,7 +17,7 @@
<dependency> <dependency>
<groupId>org.pegdown</groupId> <groupId>org.pegdown</groupId>
<artifactId>pegdown</artifactId> <artifactId>pegdown</artifactId>
<version>1.1.0</version> <version>${pegdown.version}</version>
</dependency> </dependency>
</dependencies> </dependencies>
libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt
+49 -34
View File
@@ -30,6 +30,7 @@ import org.pegdown.ast.RefLinkNode
import org.pegdown.ast.AutoLinkNode import org.pegdown.ast.AutoLinkNode
import org.pegdown.ast.ExpLinkNode import org.pegdown.ast.ExpLinkNode
import org.pegdown.Extensions import org.pegdown.Extensions
import org.jetbrains.kotlin.doc.templates.KDocTemplate
fun containerName(descriptor: DeclarationDescriptor): String = qualifiedName(descriptor.getContainingDeclaration()) fun containerName(descriptor: DeclarationDescriptor): String = qualifiedName(descriptor.getContainingDeclaration())
@@ -119,7 +120,7 @@ fun extensionProperties(properties: Collection<KProperty>): Map<KClass, List<KPr
return map return map
} }
abstract class KClassOrPackage : KAnnotated() { abstract class KClassOrPackage(model: KModel) : KAnnotated(model) {
public open val functions: SortedSet<KFunction> = TreeSet<KFunction>() public open val functions: SortedSet<KFunction> = TreeSet<KFunction>()
@@ -183,7 +184,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
KPackage(this, descriptor, name) KPackage(this, descriptor, name)
} }
if (created) { if (created) {
pkg.description = commentsFor(descriptor) configureComments(pkg, descriptor)
val scope = descriptor.getMemberScope() val scope = descriptor.getMemberScope()
addFunctions(pkg, scope) addFunctions(pkg, scope)
pkg.local = isLocal(descriptor) pkg.local = isLocal(descriptor)
@@ -191,6 +192,10 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
return pkg; return pkg;
} }
fun wikiConvert(text: String, linkRenderer: LinkRenderer): String {
return markdownProcessor.markdownToHtml(text, linkRenderer).sure()
}
protected fun isLocal(descriptor: DeclarationDescriptor): Boolean { protected fun isLocal(descriptor: DeclarationDescriptor): Boolean {
return if (descriptor is ModuleDescriptor) { return if (descriptor is ModuleDescriptor) {
true true
@@ -249,7 +254,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
} }
val function = KFunction(descriptor, owner, name, returnType, parameters) val function = KFunction(descriptor, owner, name, returnType, parameters)
addTypeParameters(function.typeParameters, descriptor.getTypeParameters()) addTypeParameters(function.typeParameters, descriptor.getTypeParameters())
function.description = commentsFor(descriptor) configureComments(function, descriptor)
val receiver = descriptor.getReceiverParameter() val receiver = descriptor.getReceiverParameter()
if (receiver is ExtensionReceiver) { if (receiver is ExtensionReceiver) {
function.extensionClass = getType(receiver.getType())?.klass function.extensionClass = getType(receiver.getType())?.klass
@@ -272,8 +277,8 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
protected fun createTypeParameter(descriptor: TypeParameterDescriptor): KTypeParameter? { protected fun createTypeParameter(descriptor: TypeParameterDescriptor): KTypeParameter? {
val name = descriptor.getName() val name = descriptor.getName()
val answer = KTypeParameter(name, descriptor) val answer = KTypeParameter(name, descriptor, this)
answer.description = commentsFor(descriptor) configureComments(answer, descriptor)
return answer return answer
} }
@@ -282,14 +287,15 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
if (returnType != null) { if (returnType != null) {
val name = descriptor.getName() val name = descriptor.getName()
val answer = KParameter(name, returnType) val answer = KParameter(name, returnType)
answer.description = commentsFor(descriptor) configureComments(answer, descriptor)
return answer return answer
} }
return null return null
} }
fun commentsFor(descriptor: DeclarationDescriptor): String {
protected fun commentsFor(descriptor: DeclarationDescriptor): String {
val psiElement = try { val psiElement = try {
BindingContextUtils.descriptorToDeclaration(context, descriptor) BindingContextUtils.descriptorToDeclaration(context, descriptor)
} catch (e: Throwable) { } catch (e: Throwable) {
@@ -328,8 +334,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
} }
buffer.append(text) buffer.append(text)
} }
val linkRenderer = CustomLinkRenderer(descriptor) return buffer.toString() ?: ""
return wikiConvert(buffer.toString() ?: "", linkRenderer)
} else { } else {
return text return text
} }
@@ -337,8 +342,9 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
return "" return ""
} }
fun wikiConvert(text: String, linkRenderer: LinkRenderer): String { fun configureComments(annotated: KAnnotated, descriptor: DeclarationDescriptor): Unit {
return markdownProcessor.markdownToHtml(text, linkRenderer).sure() val detailedText = commentsFor(descriptor).trim()
annotated.wikiDescription = detailedText
} }
fun getType(aType: JetType?): KType? { fun getType(aType: JetType?): KType? {
@@ -375,7 +381,7 @@ class KModel(var context: BindingContext, val config: KDocConfig, var title: Str
} }
} }
class CustomLinkRenderer(descriptor: DeclarationDescriptor) : LinkRenderer() { class TemplateLinkRenderer(template: KDocTemplate) : LinkRenderer() {
override fun render(node : WikiLinkNode?) : Rendering? { override fun render(node : WikiLinkNode?) : Rendering? {
println("LinkRenderer.render(WikiLinkNode): $node") println("LinkRenderer.render(WikiLinkNode): $node")
@@ -399,16 +405,27 @@ class CustomLinkRenderer(descriptor: DeclarationDescriptor) : LinkRenderer() {
} }
} }
abstract class KAnnotated { abstract class KAnnotated(val model: KModel) {
public open var description: String = "" public open var wikiDescription: String = ""
public open var detailedDescription: String = ""
get() = if ($detailedDescription.notEmpty()) $detailedDescription else description
public open var deprecated: Boolean = false public open var deprecated: Boolean = false
fun description(template: KDocTemplate): String {
val detailedText = detailedDescription(template)
val idx = detailedText.indexOf("</p>")
return if (idx > 0) {
detailedText.substring(0, idx).trimLeading("<p>")
} else {
detailedText
}
}
fun detailedDescription(template: KDocTemplate): String {
return model.wikiConvert(wikiDescription, TemplateLinkRenderer(template))
}
} }
abstract class KNamed(val name: String) : KAnnotated(), Comparable<KNamed> { abstract class KNamed(val name: String, model: KModel) : KAnnotated(model), Comparable<KNamed> {
override fun compareTo(other: KNamed): Int = name.compareTo(other.name) override fun compareTo(other: KNamed): Int = name.compareTo(other.name)
@@ -418,9 +435,9 @@ abstract class KNamed(val name: String) : KAnnotated(), Comparable<KNamed> {
} }
class KPackage(val model: KModel, val descriptor: NamespaceDescriptor, class KPackage(model: KModel, val descriptor: NamespaceDescriptor,
val name: String, val name: String,
var local: Boolean = false) : KClassOrPackage(), Comparable<KPackage> { var local: Boolean = false) : KClassOrPackage(model), Comparable<KPackage> {
override fun compareTo(other: KPackage): Int = name.compareTo(other.name) override fun compareTo(other: KPackage): Int = name.compareTo(other.name)
@@ -435,7 +452,7 @@ class KPackage(val model: KModel, val descriptor: NamespaceDescriptor,
KClass(this, descriptor, name) KClass(this, descriptor, name)
} }
if (created) { if (created) {
klass.description = model.commentsFor(descriptor) model.configureComments(klass, descriptor)
val typeConstructor = descriptor.getTypeConstructor() val typeConstructor = descriptor.getTypeConstructor()
val superTypes = typeConstructor.getSupertypes() val superTypes = typeConstructor.getSupertypes()
for (st in superTypes) { for (st in superTypes) {
@@ -508,11 +525,10 @@ class KPackage(val model: KModel, val descriptor: NamespaceDescriptor,
fun packageFunctions() = functions.filter{ it.extensionClass == null } fun packageFunctions() = functions.filter{ it.extensionClass == null }
} }
class KType(val jetType: JetType, val model: KModel, val klass: KClass?, val arguments: List<KType> = ArrayList<KType>()) : KNamed(klass?.name ?: jetType.toString()) { class KType(val jetType: JetType, model: KModel, val klass: KClass?, val arguments: List<KType> = ArrayList<KType>()) : KNamed(klass?.name ?: jetType.toString(), model) {
{ {
if (klass != null) { if (klass != null) {
this.description = klass.description this.wikiDescription = klass.wikiDescription
this.detailedDescription = klass.detailedDescription
} }
for (arg in jetType.getArguments()) { for (arg in jetType.getArguments()) {
if (arg != null) { if (arg != null) {
@@ -528,7 +544,7 @@ class KType(val jetType: JetType, val model: KModel, val klass: KClass?, val arg
override fun toString() = if (nullable) "$name?" else name override fun toString() = if (nullable) "$name?" else name
val nullable: Boolean val nullable: Boolean
get() = jetType.isNullable() get() = jetType.isNullable()
} }
class KClass(val pkg: KPackage, val descriptor: ClassDescriptor, class KClass(val pkg: KPackage, val descriptor: ClassDescriptor,
@@ -540,7 +556,7 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor,
var authors: List<String> = arrayList<String>(), var authors: List<String> = arrayList<String>(),
var baseClasses: List<KType> = arrayList<KType>(), var baseClasses: List<KType> = arrayList<KType>(),
var nestedClasses: List<KClass> = arrayList<KClass>(), var nestedClasses: List<KClass> = arrayList<KClass>(),
var sourceLine: Int = 2) : KClassOrPackage(), Comparable<KClass> { var sourceLine: Int = 2) : KClassOrPackage(pkg.model), Comparable<KClass> {
override fun compareTo(other: KClass): Int = name.compareTo(other.name) override fun compareTo(other: KClass): Int = name.compareTo(other.name)
@@ -557,8 +573,6 @@ class KClass(val pkg: KPackage, val descriptor: ClassDescriptor,
public val name: String = pkg.qualifiedName(simpleName) public val name: String = pkg.qualifiedName(simpleName)
public val model: KModel = pkg.model
public val packageName: String = pkg.name public val packageName: String = pkg.name
/** Returns the name as a directory using '/' instead of '.' */ /** Returns the name as a directory using '/' instead of '.' */
@@ -590,7 +604,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage,
var typeParameters: List<KTypeParameter> = arrayList<KTypeParameter>(), var typeParameters: List<KTypeParameter> = arrayList<KTypeParameter>(),
var exceptions: List<KClass> = arrayList<KClass>(), var exceptions: List<KClass> = arrayList<KClass>(),
var annotations: List<KAnnotation> = arrayList<KAnnotation>(), var annotations: List<KAnnotation> = arrayList<KAnnotation>(),
var sourceLine: Int = 2) : KAnnotated(), Comparable<KFunction> { var sourceLine: Int = 2) : KAnnotated(owner.model), Comparable<KFunction> {
public val parameterTypeText: String = parameters.map{ it.aType.name }.join(", ") public val parameterTypeText: String = parameters.map{ it.aType.name }.join(", ")
@@ -608,7 +622,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage,
} }
fun equals(other: KFunction) = name == other.name && this.parameterTypeText == other.parameterTypeText && fun equals(other: KFunction) = name == other.name && this.parameterTypeText == other.parameterTypeText &&
this.extensionClass == other.extensionClass && this.owner == other.owner this.extensionClass == other.extensionClass && this.owner == other.owner
fun toString() = "fun $name($parameterTypeText): $returnType" fun toString() = "fun $name($parameterTypeText): $returnType"
@@ -620,7 +634,7 @@ class KFunction(val descriptor: CallableDescriptor, val owner: KClassOrPackage,
} }
class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, val name: String, class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor, val name: String,
val returnType: KType, val extensionClass: KClass?) : KAnnotated(), Comparable<KProperty> { val returnType: KType, val extensionClass: KClass?) : KAnnotated(owner.model), Comparable<KProperty> {
override fun compareTo(other: KProperty): Int = name.compareTo(other.name) override fun compareTo(other: KProperty): Int = name.compareTo(other.name)
@@ -632,19 +646,20 @@ class KProperty(val owner: KClassOrPackage, val descriptor: PropertyDescriptor,
} }
class KParameter(val name: String, class KParameter(val name: String,
var aType: KType) : KAnnotated() { var aType: KType) : KAnnotated(aType.model) {
fun toString() = "$name: ${aType.name}" fun toString() = "$name: ${aType.name}"
} }
class KTypeParameter(val name: String, class KTypeParameter(val name: String,
val descriptor: TypeParameterDescriptor, val descriptor: TypeParameterDescriptor,
var extends: List<KClass> = arrayList<KClass>()) : KAnnotated() { model: KModel,
var extends: List<KClass> = arrayList<KClass>()) : KAnnotated(model) {
fun toString() = "$name" fun toString() = "$name"
} }
class KAnnotation(var klass: KClass) : KAnnotated() { class KAnnotation(var klass: KClass) : KAnnotated(klass.model) {
// TODO add some parameter values? // TODO add some parameter values?
libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/ClassTemplate.kt
Vendored
+2 -2
View File
@@ -195,7 +195,7 @@ Class ${klass.simpleName}</H2>
</PRE> </PRE>
<P>""") <P>""")
println(klass.detailedDescription) println(klass.detailedDescription(this))
if (klass.since.size > 0 || klass.authors.size > 0) { if (klass.since.size > 0 || klass.authors.size > 0) {
println("""<P> println("""<P>
<DL>""") <DL>""")
@@ -229,7 +229,7 @@ Class ${klass.simpleName}</H2>
<CODE>static&nbsp;class</CODE></FONT></TD> <CODE>static&nbsp;class</CODE></FONT></TD>
<TD><CODE><B><A HREF="${pkg.nameAsRelativePath}${nc.nameAsPath}.html" title="class in ${nc.packageName}">${klass.simpleName}.${nc.simpleName}</A></B></CODE> <TD><CODE><B><A HREF="${pkg.nameAsRelativePath}${nc.nameAsPath}.html" title="class in ${nc.packageName}">${klass.simpleName}.${nc.simpleName}</A></B></CODE>
<BR> <BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${nc.description} &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${nc.description(this)}
</TD>""") </TD>""")
} }
println("""</TR> println("""</TR>
libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/OverviewSummaryTemplate.kt
Vendored
+1 -1
View File
@@ -105,7 +105,7 @@ ${model.title}
for (p in model.packages) { for (p in model.packages) {
println("""<TR BGCOLOR="white" CLASS="TableRowColor"> println("""<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="20%"><B><A HREF="${p.nameAsPath}/package-summary.html">${p.name}</A></B></TD> <TD WIDTH="20%"><B><A HREF="${p.nameAsPath}/package-summary.html">${p.name}</A></B></TD>
<TD>${p.description}</TD> <TD>${p.description(this)}</TD>
</TR>""") </TR>""")
} }
println("""</TABLE> println("""</TABLE>
libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageSummaryTemplate.kt
Vendored
+4 -4
View File
@@ -105,7 +105,7 @@ function windowTitle()
println("""</FONT><H2> println("""</FONT><H2>
Package ${pkg.name} Package ${pkg.name}
</H2> </H2>
${pkg.description} ${pkg.description(this)}
<P> <P>
<B>See:</B> <B>See:</B>
<BR> <BR>
@@ -127,7 +127,7 @@ Package ${pkg.name} Description
</H2> </H2>
<P> <P>
${pkg.detailedDescription} ${pkg.detailedDescription(this)}
<h2>Contents</h2> <h2>Contents</h2>
@@ -229,7 +229,7 @@ Copyright &#169; 2010-2012. All Rights Reserved.
for (c in classes) { for (c in classes) {
println("""<TR BGCOLOR="white" CLASS="TableRowColor"> println("""<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="${pkg.nameAsRelativePath}${c.nameAsPath}.html" title="$kind in ${pkg.name}">${c.simpleName}</A></B></TD> <TD WIDTH="15%"><B><A HREF="${pkg.nameAsRelativePath}${c.nameAsPath}.html" title="$kind in ${pkg.name}">${c.simpleName}</A></B></TD>
<TD>${c.description}</TD> <TD>${c.description(this)}</TD>
</TR>""") </TR>""")
} }
println("""</TABLE> println("""</TABLE>
@@ -252,7 +252,7 @@ Copyright &#169; 2010-2012. All Rights Reserved.
for (f in functions) { for (f in functions) {
println("""<TR BGCOLOR="white" CLASS="TableRowColor"> println("""<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="${href(f)}" title="function in ${pkg.name}">${f.name}</A></B></TD> <TD WIDTH="15%"><B><A HREF="${href(f)}" title="function in ${pkg.name}">${f.name}</A></B></TD>
<TD>${f.description}</TD> <TD>${f.description(this)}</TD>
</TR>""") </TR>""")
} }
println("""</TABLE> println("""</TABLE>
libraries/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/templates/PackageTemplateSupport.kt
Vendored
+5 -5
View File
@@ -65,11 +65,11 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
println("""</CODE>""") println("""</CODE>""")
println("") println("")
if (true) { if (true) {
val detail = function.detailedDescription println("""<BR>""")
println("""${detail}""") println("""${function.description(this)}""")
} else { } else {
println("""<BR>""") println("""<BR>""")
println("""&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${deprecated}&nbsp;${function.detailedDescription}</TD>""") println("""&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${deprecated}&nbsp;${function.detailedDescription(this)}</TD>""")
} }
println("""</TD>""") println("""</TD>""")
println("""</TR>""") println("""</TR>""")
@@ -120,7 +120,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
} }
println("""</PRE>""") println("""</PRE>""")
println(function.detailedDescription) println(function.detailedDescription(this))
/* TODO /* TODO
println("""<DL> println("""<DL>
<DD><B>Deprecated.</B>&nbsp;TODO text <DD><B>Deprecated.</B>&nbsp;TODO text
@@ -188,7 +188,7 @@ abstract class PackageTemplateSupport(open val pkg: KPackage) : KDocTemplate() {
println("""</CODE>""") println("""</CODE>""")
println("""""") println("""""")
println("""<BR>""") println("""<BR>""")
println("""&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${deprecated}&nbsp;${property.detailedDescription}</TD>""") println("""&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;${deprecated}&nbsp;${property.detailedDescription(this)}</TD>""")
println("""</TR>""") println("""</TR>""")
} }