aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--src/Formats/StructuredFormatService.kt8
-rw-r--r--src/Kotlin/DocumentationBuilder.kt42
-rw-r--r--src/Model/DocumentationNode.kt2
-rw-r--r--src/main.kt28
-rw-r--r--test/src/TestAPI.kt2
5 files changed, 77 insertions, 5 deletions
diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt
index bfb69d1d..458fda35 100644
--- a/src/Formats/StructuredFormatService.kt
+++ b/src/Formats/StructuredFormatService.kt
@@ -121,6 +121,7 @@ public abstract class StructuredFormatService(val locationService: LocationServi
appendBlockCode(to, formatText(location, languageService.render(it)))
it.appendOverrides(to)
it.appendDeprecation(to)
+ it.appendSourceLink(to)
}
appendLine(to, summary)
appendLine(to)
@@ -148,6 +149,13 @@ public abstract class StructuredFormatService(val locationService: LocationServi
}
}
+ private fun DocumentationNode.appendSourceLink(to: StringBuilder) {
+ val sourceUrl = details(DocumentationNode.Kind.SourceUrl).firstOrNull()
+ if (sourceUrl != null) {
+ appendLine(to, formatLink("Source", sourceUrl.name))
+ }
+ }
+
fun appendLocation(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>) {
val breakdownByName = nodes.groupBy { node -> node.name }
for ((name, items) in breakdownByName) {
diff --git a/src/Kotlin/DocumentationBuilder.kt b/src/Kotlin/DocumentationBuilder.kt
index d7ba8a32..1e09e110 100644
--- a/src/Kotlin/DocumentationBuilder.kt
+++ b/src/Kotlin/DocumentationBuilder.kt
@@ -12,8 +12,14 @@ import org.jetbrains.kotlin.descriptors.annotations.AnnotationDescriptor
import org.jetbrains.kotlin.resolve.constants.CompileTimeConstant
import com.intellij.openapi.util.text.StringUtil
import org.jetbrains.kotlin.descriptors.impl.EnumEntrySyntheticClassDescriptor
+import org.jetbrains.kotlin.resolve.source.getPsi
+import java.io.File
+import com.intellij.psi.PsiDocumentManager
+import com.intellij.psi.PsiNameIdentifierOwner
+import com.intellij.psi.PsiElement
-public data class DocumentationOptions(val includeNonPublic: Boolean = false)
+public data class DocumentationOptions(val includeNonPublic: Boolean = false,
+ val sourceLinks: List<SourceLinkDefinition>)
private fun isSamePackage(descriptor1: DeclarationDescriptor, descriptor2: DeclarationDescriptor): Boolean {
val package1 = DescriptorUtils.getParentOfType(descriptor1, javaClass<PackageFragmentDescriptor>())
@@ -142,6 +148,36 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
}
}
+ fun DocumentationNode.appendSourceLink(sourceElement: SourceElement) {
+ val psi = getTargetElement(sourceElement)
+ val path = psi?.getContainingFile()?.getVirtualFile()?.getPath()
+ if (path == null) {
+ return
+ }
+ val absPath = File(path).getAbsolutePath()
+ val linkDef = findSourceLinkDefinition(absPath)
+ if (linkDef != null) {
+ var url = linkDef.url + path.substring(linkDef.path.length())
+ if (linkDef.lineSuffix != null) {
+ val doc = PsiDocumentManager.getInstance(psi!!.getProject()).getDocument(psi.getContainingFile())
+ if (doc != null) {
+ // IJ uses 0-based line-numbers; external source browsers use 1-based
+ val line = doc.getLineNumber(psi.getTextRange().getStartOffset()) + 1
+ url += linkDef.lineSuffix + line.toString()
+ }
+ }
+ append(DocumentationNode(url, Content.Empty, DocumentationNode.Kind.SourceUrl),
+ DocumentationReference.Kind.Detail);
+ }
+ }
+
+ private fun getTargetElement(sourceElement: SourceElement): PsiElement? {
+ val psi = sourceElement.getPsi()
+ return if (psi is PsiNameIdentifierOwner) psi.getNameIdentifier() else psi
+ }
+
+ fun findSourceLinkDefinition(path: String) = options.sourceLinks.firstOrNull { path.startsWith(it.path) }
+
fun DocumentationNode.appendChild(descriptor: DeclarationDescriptor, kind: DocumentationReference.Kind) {
// do not include generated code
if (descriptor is CallableMemberDescriptor && descriptor.getKind() != CallableMemberDescriptor.Kind.DECLARATION)
@@ -232,6 +268,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
DocumentationReference.Kind.Member)
}
node.appendAnnotations(this)
+ node.appendSourceLink(getSource())
register(this, node)
return node
}
@@ -263,6 +300,8 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
node.appendChildren(getValueParameters(), DocumentationReference.Kind.Detail)
node.appendType(getReturnType())
node.appendAnnotations(this)
+ node.appendSourceLink(getSource())
+
register(this, node)
return node
@@ -285,6 +324,7 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
getExtensionReceiverParameter()?.let { node.appendChild(it, DocumentationReference.Kind.Detail) }
node.appendType(getReturnType())
node.appendAnnotations(this)
+ node.appendSourceLink(getSource())
if (isVar()) {
node.append(DocumentationNode("var", Content.Empty, DocumentationNode.Kind.Modifier),
DocumentationReference.Kind.Detail)
diff --git a/src/Model/DocumentationNode.kt b/src/Model/DocumentationNode.kt
index 6e707cce..a666b486 100644
--- a/src/Model/DocumentationNode.kt
+++ b/src/Model/DocumentationNode.kt
@@ -97,6 +97,8 @@ public open class DocumentationNode(val name: String,
Annotation
Value
+
+ SourceUrl
}
}
diff --git a/src/main.kt b/src/main.kt
index 24853be5..989e8a36 100644
--- a/src/main.kt
+++ b/src/main.kt
@@ -6,7 +6,6 @@ import org.jetbrains.kotlin.cli.common.messages.*
import org.jetbrains.kotlin.cli.common.arguments.*
import org.jetbrains.kotlin.utils.PathUtil
import java.io.File
-import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
import org.jetbrains.kotlin.name.FqName
class DokkaArguments {
@@ -14,6 +13,10 @@ class DokkaArguments {
ValueDescription("<path>")
public var src: String = ""
+ Argument(value = "srcLink", description = "Mapping between a source directory and a Web site for browsing the code")
+ ValueDescription("<path>=<url>[#lineSuffix]")
+ public var srcLink: String = ""
+
Argument(value = "include", description = "Markdown files to load (allows many paths separated by the system path separator)")
ValueDescription("<path>")
public var include: String = ""
@@ -40,6 +43,15 @@ class DokkaArguments {
}
+class SourceLinkDefinition(val path: String, val url: String, val lineSuffix: String?)
+
+private fun parseSourceLinkDefinition(srcLink: String): SourceLinkDefinition {
+ val (path, urlAndLine) = srcLink.split('=')
+ return SourceLinkDefinition(File(path).getAbsolutePath(),
+ urlAndLine.substringBefore("#"),
+ urlAndLine.substringAfter("#", "").let { if (it.isEmpty()) null else "#" + it })
+}
+
public fun main(args: Array<String>) {
val arguments = DokkaArguments()
val freeArgs: List<String> = Args.parse(arguments, args) ?: listOf()
@@ -47,6 +59,15 @@ public fun main(args: Array<String>) {
val samples = if (arguments.samples.isNotEmpty()) arguments.samples.split(File.pathSeparatorChar).toList() else listOf()
val includes = if (arguments.include.isNotEmpty()) arguments.include.split(File.pathSeparatorChar).toList() else listOf()
+ val sourceLinks = if (arguments.srcLink.isNotEmpty() && arguments.srcLink.contains("="))
+ listOf(parseSourceLinkDefinition(arguments.srcLink))
+ else {
+ if (arguments.srcLink.isNotEmpty()) {
+ println("Warning: Invalid -srcLink syntax. Expected: <path>=<url>[#lineSuffix]. No source links will be generated.")
+ }
+ listOf()
+ }
+
val environment = AnalysisEnvironment(MessageCollectorPlainTextToStream.PLAIN_TEXT_TO_SYSTEM_ERR) {
addClasspath(PathUtil.getJdkClassesRoots())
// addClasspath(PathUtil.getKotlinPathsForCompiler().getRuntimePath())
@@ -79,7 +100,7 @@ public fun main(args: Array<String>) {
}
}
val fragments = fragmentFiles.map { session.getPackageFragment(it.getPackageFqName()) }.filterNotNull().distinct()
- val options = DocumentationOptions()
+ val options = DocumentationOptions(false, sourceLinks)
val documentationBuilder = DocumentationBuilder(session, options)
with(documentationBuilder) {
@@ -133,4 +154,5 @@ public fun main(args: Array<String>) {
println()
println("Done.")
Disposer.dispose(environment)
-} \ No newline at end of file
+}
+
diff --git a/test/src/TestAPI.kt b/test/src/TestAPI.kt
index 4d64014e..f3c5f8c8 100644
--- a/test/src/TestAPI.kt
+++ b/test/src/TestAPI.kt
@@ -32,7 +32,7 @@ public fun verifyModel(vararg files: String, verifier: (DocumentationModule) ->
addSources(files.toList())
}
- val options = DocumentationOptions(includeNonPublic = true)
+ val options = DocumentationOptions(includeNonPublic = true, sourceLinks = listOf<SourceLinkDefinition>())
val documentation = environment.withContext { environment, session ->
val fragments = environment.getSourceFiles().map { session.getPackageFragment(it.getPackageFqName()) }.filterNotNull().distinct()
generated by cgit (git 2.46.0) at 2024-11-30 20:39:33 +0000