aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/Formats/HtmlFormatService.kt4
-rw-r--r--src/Formats/MarkdownFormatService.kt4
-rw-r--r--src/Formats/StructuredFormatService.kt12
-rw-r--r--src/Kotlin/DocumentationBuilder.kt30
-rw-r--r--src/Locations/LocationService.kt9
-rw-r--r--src/Model/DocumentationReference.kt1
6 files changed, 46 insertions, 14 deletions
diff --git a/src/Formats/HtmlFormatService.kt b/src/Formats/HtmlFormatService.kt
index 733425d7..d5331422 100644
--- a/src/Formats/HtmlFormatService.kt
+++ b/src/Formats/HtmlFormatService.kt
@@ -50,6 +50,10 @@ public open class HtmlFormatService(locationService: LocationService,
to.appendln("<br/>")
}
+ override fun appendAnchor(to: StringBuilder, anchor: String) {
+ to.appendln("<a name=\"${anchor.htmlEscape()}\"></a>")
+ }
+
override fun appendTable(to: StringBuilder, body: () -> Unit) {
to.appendln("<table>")
body()
diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt
index 281ca21d..2bd12c53 100644
--- a/src/Formats/MarkdownFormatService.kt
+++ b/src/Formats/MarkdownFormatService.kt
@@ -59,6 +59,10 @@ public open class MarkdownFormatService(locationService: LocationService,
to.appendln(text)
}
+ override fun appendAnchor(to: StringBuilder, anchor: String) {
+ // no anchors in Markdown
+ }
+
override public fun appendParagraph(to: StringBuilder, text: String) {
to.appendln()
to.appendln(text)
diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt
index 14eb490a..d2e2436b 100644
--- a/src/Formats/StructuredFormatService.kt
+++ b/src/Formats/StructuredFormatService.kt
@@ -16,6 +16,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
abstract public fun appendParagraph(to: StringBuilder, text: String)
abstract public fun appendLine(to: StringBuilder, text: String)
public abstract fun appendLine(to: StringBuilder)
+ public abstract fun appendAnchor(to: StringBuilder, anchor: String)
public abstract fun appendTable(to: StringBuilder, body: () -> Unit)
public abstract fun appendTableHeader(to: StringBuilder, body: () -> Unit)
@@ -56,7 +57,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
is ContentListItem -> append(formatListItem(formatText(location, content.children)))
is ContentNodeLink -> {
- val linkTo = location.relativePathTo(locationService.location(content.node))
+ val linkTo = locationHref(location, content.node)
val linkText = formatText(location, content.children)
append(formatLink(linkText, linkTo))
}
@@ -81,6 +82,14 @@ public abstract class StructuredFormatService(locationService: LocationService,
return FormatLink(to.name, locationService.relativePathToLocation(from, to))
}
+ fun locationHref(from: Location, to: DocumentationNode): String {
+ val topLevelPage = to.references(DocumentationReference.Kind.TopLevelPage).singleOrNull()?.to
+ if (topLevelPage != null) {
+ return from.relativePathTo(locationService.location(topLevelPage), to.name)
+ }
+ return from.relativePathTo(locationService.location(to))
+ }
+
fun appendDocumentation(location: Location, to: StringBuilder, overloads: Iterable<DocumentationNode>) {
val breakdownBySummary = overloads.groupByTo(LinkedHashMap()) { node -> node.content }
@@ -124,6 +133,7 @@ public abstract class StructuredFormatService(locationService: LocationService,
subjectSections.forEach {
val subjectName = it.subjectName
if (subjectName != null) {
+ appendAnchor(to, subjectName)
to.append(formatCode(subjectName)).append(" - ")
to.append(formatText(location, it))
appendLine(to)
diff --git a/src/Kotlin/DocumentationBuilder.kt b/src/Kotlin/DocumentationBuilder.kt
index 0ad93801..861e0a7b 100644
--- a/src/Kotlin/DocumentationBuilder.kt
+++ b/src/Kotlin/DocumentationBuilder.kt
@@ -185,22 +185,34 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
appendSourceLink(sourceElement.getPsi(), options.sourceLinks)
}
- fun DocumentationNode.appendChild(descriptor: DeclarationDescriptor, kind: DocumentationReference.Kind) {
+ fun DocumentationNode.appendChild(descriptor: DeclarationDescriptor, kind: DocumentationReference.Kind): DocumentationNode? {
// do not include generated code
if (descriptor is CallableMemberDescriptor && descriptor.getKind() != CallableMemberDescriptor.Kind.DECLARATION)
- return
+ return null
if (options.includeNonPublic
|| descriptor !is MemberDescriptor
|| descriptor.getVisibility() in visibleToDocumentation) {
- append(descriptor.build(), kind)
+ val node = descriptor.build()
+ append(node, kind)
+ return node
}
+ return null
}
fun DocumentationNode.appendChildren(descriptors: Iterable<DeclarationDescriptor>, kind: DocumentationReference.Kind) {
descriptors.forEach { descriptor -> appendChild(descriptor, kind) }
}
+ fun DocumentationNode.appendInPageChildren(descriptors: Iterable<DeclarationDescriptor>, kind: DocumentationReference.Kind) {
+ descriptors.forEach { descriptor ->
+ val node = appendChild(descriptor, kind)
+ if (node != null) {
+ node.addReferenceTo(this, DocumentationReference.Kind.TopLevelPage)
+ }
+ }
+ }
+
fun DocumentationNode.getParentForPackageMember(descriptor: DeclarationDescriptor,
externalClassNodes: MutableMap<FqName, DocumentationNode>): DocumentationNode {
if (descriptor is CallableMemberDescriptor) {
@@ -263,7 +275,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
}
node.appendSupertypes(this)
if (getKind() != ClassKind.OBJECT && getKind() != ClassKind.ENUM_ENTRY) {
- node.appendChildren(getTypeConstructor().getParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getTypeConstructor().getParameters(), DocumentationReference.Kind.Detail)
val constructorsToDocument = if (getKind() == ClassKind.ENUM_CLASS)
getConstructors().filter { it.getValueParameters().size() > 0 }
else
@@ -285,7 +297,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
fun ConstructorDescriptor.build(): DocumentationNode {
val node = DocumentationNode(this, Kind.Constructor)
- node.appendChildren(getValueParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getValueParameters(), DocumentationReference.Kind.Detail)
register(this, node)
return node
}
@@ -305,9 +317,9 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
fun FunctionDescriptor.build(): DocumentationNode {
val node = DocumentationNode(this, if (inClassObject()) Kind.DefaultObjectFunction else Kind.Function)
- node.appendChildren(getTypeParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getTypeParameters(), DocumentationReference.Kind.Detail)
getExtensionReceiverParameter()?.let { node.appendChild(it, DocumentationReference.Kind.Detail) }
- node.appendChildren(getValueParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getValueParameters(), DocumentationReference.Kind.Detail)
node.appendType(getReturnType())
node.appendAnnotations(this)
node.appendSourceLink(getSource())
@@ -322,7 +334,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
val specialName = getName().asString().drop(1).takeWhile { it != '-' }
val node = DocumentationNode(specialName, doc, Kind.PropertyAccessor).withModifiers(this)
- node.appendChildren(getValueParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getValueParameters(), DocumentationReference.Kind.Detail)
node.appendType(getReturnType())
register(this, node)
return node
@@ -330,7 +342,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
fun PropertyDescriptor.build(): DocumentationNode {
val node = DocumentationNode(this, if (inClassObject()) Kind.DefaultObjectProperty else Kind.Property)
- node.appendChildren(getTypeParameters(), DocumentationReference.Kind.Detail)
+ node.appendInPageChildren(getTypeParameters(), DocumentationReference.Kind.Detail)
getExtensionReceiverParameter()?.let { node.appendChild(it, DocumentationReference.Kind.Detail) }
node.appendType(getReturnType())
node.appendAnnotations(this)
diff --git a/src/Locations/LocationService.kt b/src/Locations/LocationService.kt
index 96cd0c51..500b89f2 100644
--- a/src/Locations/LocationService.kt
+++ b/src/Locations/LocationService.kt
@@ -4,7 +4,7 @@ import java.io.File
public trait Location {
val path: String get
- fun relativePathTo(other: Location): String
+ fun relativePathTo(other: Location, anchor: String? = null): String
}
/**
@@ -19,12 +19,13 @@ public data class FileLocation(val file: File): Location {
override val path : String
get() = file.path
- override fun relativePathTo(other: Location): String {
+ override fun relativePathTo(other: Location, anchor: String?): String {
if (other !is FileLocation) {
throw IllegalArgumentException("$other is not a FileLocation")
}
val ownerFolder = file.getParentFile()!!
- return ownerFolder.getRelativePath(other.file).path
+ val relativePath = ownerFolder.getRelativePath(other.file).path
+ return if (anchor == null) relativePath else relativePath + "#" + anchor
}
}
@@ -62,5 +63,5 @@ public fun identifierToFilename(path: String): String {
* Returns relative location between two nodes. Used for relative links in documentation.
*/
fun LocationService.relativePathToLocation(owner: DocumentationNode, node: DocumentationNode): String {
- return location(owner).relativePathTo(location(node))
+ return location(owner).relativePathTo(location(node), null)
}
diff --git a/src/Model/DocumentationReference.kt b/src/Model/DocumentationReference.kt
index bd40f0f5..d7ad5f9e 100644
--- a/src/Model/DocumentationReference.kt
+++ b/src/Model/DocumentationReference.kt
@@ -11,6 +11,7 @@ public data class DocumentationReference(val from: DocumentationNode, val to: Do
Override
Annotation
Deprecation
+ TopLevelPage
}
}
generated by cgit (git 2.46.0) at 2024-11-24 05:08:21 +0000