diff options
Diffstat (limited to 'docs-developer/src/doc/docs/developer_guide/architecture/data_model')
3 files changed, 486 insertions, 0 deletions
diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md new file mode 100644 index 00000000..b30780fc --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/documentable_model.md @@ -0,0 +1,251 @@ +# Documentable Model + +The Documentable model represents the data that is parsed from some programming language sources. Think of this data as +of something that could be seen or produced by a compiler frontend, it's not far off from the truth. + +By default, the documentables are created from: + +* Descriptors (Kotlin's K1 compiler) +* Symbols (Kotlin's K2 compiler) +* [PSI](https://plugins.jetbrains.com/docs/intellij/psi.html) (Java's model). + +Code-wise, you can have a look at following classes: + +* `DefaultDescriptorToDocumentableTranslator` - responsible for Kotlin -> `Documentable` mapping +* `DefaultPsiToDocumentableTranslator` - responsible for Java -> `Documentable` mapping + +Upon creation, the documentable model represents a collection of trees, each with `DModule` as root. + +Take some arbitrary Kotlin source code that is located within the same module: + +```kotlin +// Package 1 +class Clazz(val property: String) { + fun function(parameter: String) {} +} + +fun topLevelFunction() {} + +// Package 2 +enum class Enum { } + +val topLevelProperty: String +``` + +This would be represented roughly as the following Documentable tree: + +```mermaid +flowchart TD + DModule --> firstPackage[DPackage] + firstPackage --> DClass + firstPackage --> toplevelfunction[DFunction] + DClass --> DProperty + DClass --> DFunction + DFunction --> DParameter + DModule --> secondPackage[DPackage] + secondPackage --> DEnum + secondPackage --> secondPackageProperty[DProperty] +``` + +At later stages of transformation, all trees are folded into one by +[DocumentableMerger](../extension_points/core_extension_points.md#documentablemerger). + +## Documentable + +The main building block of the documentable model is the `Documentable` class. It is the base class for all more specific +types. All implementations represent elements of source code with mostly self-explanatory names: `DFunction`, +`DPackage`, `DProperty`, and so on. + +`DClasslike` is the base class for all class-like documentables, such as `DClass`, `DEnum`, `DAnnotation` and others. + +The contents of each documentable normally represent what you would see in the source code. + +For example, if you open +`DClass`, you should find that it contains references to functions, properties, companion objects, constructors and so +on. `DEnum` should have references to its entries, and `DPackage` can have references to both classlikes and top-level +functions and properties (Kotlin-specific). + +Here's an example of a documentable: + +```kotlin +data class DClass( + val dri: DRI, + val name: String, + val constructors: List<DFunction>, + val functions: List<DFunction>, + val properties: List<DProperty>, + val classlikes: List<DClasslike>, + val sources: SourceSetDependent<DocumentableSource>, + val visibility: SourceSetDependent<Visibility>, + val companion: DObject?, + val generics: List<DTypeParameter>, + val supertypes: SourceSetDependent<List<TypeConstructorWithKind>>, + val documentation: SourceSetDependent<DocumentationNode>, + val expectPresentInSet: DokkaSourceSet?, + val modifier: SourceSetDependent<Modifier>, + val sourceSets: Set<DokkaSourceSet>, + val isExpectActual: Boolean, + val extra: PropertyContainer<DClass> = PropertyContainer.empty() +) : DClasslike(), WithAbstraction, WithCompanion, WithConstructors, + WithGenerics, WithSupertypes, WithExtraProperties<DClass> +``` + +___ + +There are three non-documentable classes that are important for this model: + +* `DRI` +* `SourceSetDependent` +* `ExtraProperty`. + +### DRI + +`DRI` stans for _Dokka Resource Identifier_ - a unique value that identifies a specific `Documentable`. +All references and relations between the documentables (other than direct ownership) are described using `DRI`. + +For example, `DFunction` with a parameter of type `Foo` only has `Foo`'s `DRI`, but not the actual reference +to `Foo`'s `Documentable` object. + +#### Example + +For an example of how a `DRI` can look like, let's take the `limitedParallelism` function from `kotlinx.coroutines`: + +```kotlin +package kotlinx.coroutines + +import ... + +public abstract class MainCoroutineDispatcher : CoroutineDispatcher() { + + override fun limitedParallelism(parallelism: Int): CoroutineDispatcher { + ... + } +} +``` + +If we were to re-create the DRI of this function in code, it would look something like this: + +```kotlin +DRI( + packageName = "kotlinx.coroutines", + classNames = "MainCoroutineDispatcher", + callable = Callable( + name = "limitedParallelism", + receiver = null, + params = listOf( + TypeConstructor( + fullyQualifiedName = "kotlin.Int", + params = emptyList() + ) + ) + ), + target = PointingToDeclaration, + extra = null +) +``` + +If you format it as `String`, it would look like this: + +``` +kotlinx.coroutines/MainCoroutineDispatcher/limitedParallelism/#kotlin.Int/PointingToDeclaration/ +``` + +### SourceSetDependent + +`SourceSetDependent` helps handling multiplatform data by associating platform-specific data (declared with either +`expect` or `actual` modifiers) with particular +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets). + +This comes in handy if the `expect` / `actual` declarations differ. For example, the default value for `actual` might +differ from that declared in `expect`, or code comments written for `expect` might be different from what's written +for `actual`. + +Under the hood, it's a `typealias` to a `Map`: + +```kotlin +typealias SourceSetDependent<T> = Map<DokkaSourceSet, T> +``` + +### ExtraProperty + +`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly +recommended to use extras to provide any additional information when creating custom Dokka plugins. + +This element is a bit more complex, so you can read more about how to use it +[in a separate section](extra.md). + +___ + +## Documentation model + +The Documentation model is used alongside documentables to store data obtained by parsing +code comments (such as KDocs / Javadocs). + +### DocTag + +`DocTag` describes a specific documentation syntax element. + +It's universal across language sources. For example, the DocTag `B` is the same for `**bold**` in Kotlin and +`<b>bold</b>` in Java. + +However, some DocTag elements are specific to one language. There are many such examples for Java, because it allows +HTML tags inside the Javadoc comments, some of which are simply not possible to reproduce with Markdown that KDocs use. + +`DocTag` elements can be deeply nested with other `DocTag` children elements. + +Examples: + +```kotlin +data class H1( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class H2( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class Strikethrough( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class Strong( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : DocTag() + +data class CodeBlock( + override val children: List<DocTag> = emptyList(), + override val params: Map<String, String> = emptyMap() +) : Code() + +``` + +### TagWrapper + +`TagWrapper` describes the whole comment description or a specific comment tag. For example: `@see` / `@author` / `@return`. + +Since each such section may contain formatted text inside it, each `TagWrapper` has `DocTag` children. + +```kotlin +/** + * @author **Ben Affleck* + * @return nothing, except _sometimes_ it may throw an [Error] + */ +fun foo() {} +``` + +### DocumentationNode + +`DocumentationNode` acts as a container for multiple `TagWrapper` elements for a specific `Documentable`, usually +used like this: + +```kotlin +data class DFunction( + ... + val documentation: SourceSetDependent<DocumentationNode>, + ... +) +``` diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md new file mode 100644 index 00000000..d7412e36 --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/extra.md @@ -0,0 +1,91 @@ +# Extra + +## Introduction + +`ExtraProperty` is used to store any additional information that falls outside of the regular model. It is highly +recommended to use extras to provide any additional information when creating custom Dokka plugins. + +`ExtraProperty` classes are available both in the [Documentable](documentable_model.md) and the [Content](page_content.md#content-model) +models. + +To create a new extra, you need to implement the `ExtraProperty` interface. It is advised to use the following pattern +when declaring new extras: + +```kotlin +data class CustomExtra( + [any data relevant to your extra], + [any data relevant to your extra] +): ExtraProperty<Documentable> { + override val key: CustomExtra.Key<Documentable, *> = CustomExtra + companion object : CustomExtra.Key<Documentable, CustomExtra> +} +``` + +Merge strategy (the `mergeStrategyFor` method) for extras is invoked during the +[merging](../extension_points/core_extension_points.md#documentablemerger) of the documentables from different +[source sets](https://kotlinlang.org/docs/multiplatform-discover-project.html#source-sets), when the documentables being +merged have their own `Extra` of the same type. + +## PropertyContainer + +All extras for `ContentNode` and `Documentable` classes are stored in the `PropertyContainer<C : Any>` class instances. + +```kotlin +data class DFunction( + ... + override val extra: PropertyContainer<DFunction> = PropertyContainer.empty() + ... +) : WithExtraProperties<DFunction> +``` + +`PropertyContainer` has a number of convenient functions for handling extras in a collection-like manner. + +The generic class parameter `C` limits the types of properties that can be stored in the container - it must +match the generic `C` class parameter from the `ExtraProperty` interface. This allows creating extra properties +which can only be stored in a specific `Documentable`. + +## Usage example + +In following example we will create a `DFunction`-only extra property, store it and then retrieve its value: + +```kotlin +// Extra that is applicable only to DFunction +data class CustomExtra(val customExtraValue: String) : ExtraProperty<DFunction> { + override val key: ExtraProperty.Key<Documentable, *> = CustomExtra + companion object: ExtraProperty.Key<Documentable, CustomExtra> +} + +// Storing it inside the documentable +fun DFunction.withCustomExtraProperty(data: String): DFunction { + return this.copy( + extra = extra + CustomExtra(data) + ) +} + +// Retrieveing it from the documentable +fun DFunction.getCustomExtraPropertyValue(): String? { + return this.extra[CustomExtra]?.customExtraValue +} +``` + +___ + +You can also use extras as markers, without storing any data in them: + +```kotlin + +object MarkerExtra : ExtraProperty<Any>, ExtraProperty.Key<Any, MarkerExtra> { + override val key: ExtraProperty.Key<Any, *> = this +} + +fun Documentable.markIfFunction(): Documentable { + return when(this) { + is DFunction -> this.copy(extra = extra + MarkerExtra) + else -> this + } +} + +fun WithExtraProperties<Documentable>.isMarked(): Boolean { + return this.extra[MarkerExtra] != null +} +``` diff --git a/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md new file mode 100644 index 00000000..eb85200f --- /dev/null +++ b/docs-developer/src/doc/docs/developer_guide/architecture/data_model/page_content.md @@ -0,0 +1,144 @@ +# Page / Content Model + +Even though the `Page` and `Content` models reside on the same level (under `Page`), it is easier to view them as two +different models altogether, even though `Content` is only used in conjunction with and inside the `Page` model only. + +## Page + +The Page model represents the structure of documentation pages to be generated. During rendering, each page +is processed separately, so one page corresponds to exactly one output file. + +The Page model is independent of the final output format. In other words, it's universal. Which file extension the pages +should be created as (`.html`, `.md`, etc), and how, is up to the +[Renderer](../extension_points/core_extension_points.md#renderer) extension. + +Subclasses of the `PageNode` class represent the different kinds of pages, such as `ModulePage`, `PackagePage`, +`ClasslikePage`, `MemberPage` and so on. + +The Page model can be represented as a tree, with `RootPageNode` at the root. + +Here's an example of how an arbitrary project's `Page` tree might look like, if the project consists of a module with +3 packages, one of which contains a top level function, a top level property and a class, inside which there's a function +and a property: + +```mermaid +flowchart TD + RootPageNode --> firstPackage[PackagePageNode] + RootPageNode --> secondPackage[PackagePageNode] + RootPageNode --> thirdPackage[PackagePageNode] + firstPackage --> firstPackageFirstMember[MemberPageNode - Function] + firstPackage --> firstPackageSecondMember[MemberPageNode - Property] + firstPackage ---> firstPackageClasslike[ClasslikePageNode - Class] + firstPackageClasslike --> firstPackageClasslikeFirstMember[MemberPageNode - Function] + firstPackageClasslike --> firstPackageClasslikeSecondMember[MemberPageNode - Property] + secondPackage --> etcOne[...] + thirdPackage --> etcTwo[...] +``` + +Almost all pages are derivatives of `ContentPage` - it's the type of a page that has user-visible content on it. + +## Content Model + +The Content model describes what the pages consist of. It is essentially a set of building blocks that you can put +together to represent some content. It is also output-format independent and universal. + +For an example, have a look at the subclasses of `ContentNode`: `ContentText`, `ContentList`, `ContentTable`, +`ContentCodeBlock`, `ContentHeader` and so on -- all self-explanatory. You can group chunks of content together with +`ContentGroup` - for example, to wrap all children with a style. + +```kotlin +// real example of composing content using the `DocumentableContentBuilder` DSL +orderedList { + item { + text("This list contains a nested table:") + table { + header { + text("Col1") + text("Col2") + } + row { + text("Text1") + text("Text2") + } + } + } + item { + group(styles = setOf(TextStyle.Bold)) { + text("This is bald") + text("This is also bald") + } + } +} +``` + +It is the responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it, +be it visually (html pages) or otherwise (json). + +For instance, `HtmlRenderer` might render `ContentCodeBlock` as `<code>text</code>`, but `CommonmarkRenderer` might +render it using backticks. + +### DCI + +Each node is identified by a unique `DCI`, which stands for _Dokka Content Identifier_. + +`DCI` aggregates `DRI`s of all documentables that are used by the given `ContentNode`. + +```kotlin +data class DCI(val dri: Set<DRI>, val kind: Kind) +``` + +All references to other nodes (other than direct ownership) are described using `DCI`. + +### ContentKind + +`ContentKind` represents a grouping of content of one kind that can be rendered as part of a composite +page, like a single one tab or a block within a class's page. + +For example, on the same page that describes a class you can have multiple sections (== `ContentKind`s). +One to describe functions, one to describe properties, another one to describe the constructors, and so on. + +### Styles + +Each `ContentNode` has a `styles` property in case you want to indicate to the `Renderer` that this content needs to be +rendered in a certain way. + +```kotlin +group(styles = setOf(TextStyle.Paragraph)) { + text("Text1", styles = setOf(TextStyle.Bold)) + text("Text2", styles = setOf(TextStyle.Italic)) +} +``` + +It is responsibility of the `Renderer` (i.e a specific output format) to render it in a way the user can process it. +For instance, `HtmlRenderer` might render `TextStyle.Bold` as `<b>text</b>`, but `CommonmarkRenderer` might render it +as `**text**`. + +There's a number of existing styles that you can use, most of them are supported by the `HtmlRenderer` extension out of +the box: + +```kotlin +// for code highlighting +enum class TokenStyle : Style { + Keyword, Punctuation, Function, Operator, Annotation, + Number, String, Boolean, Constant, Builtin, ... +} + +enum class TextStyle : Style { + Bold, Italic, Strong, Strikethrough, Paragraph, ... +} + +enum class ContentStyle : Style { + TabbedContent, RunnableSample, Wrapped, Indented, ... +} +``` + +### Extra + +`ExtraProperty` is used to store any additional information that falls outside of the regular model. + +It is highly recommended to use extras to provide any additional information when creating custom Dokka plugins. + +All `ExtraProperty` elements from the `Documentable` model are propagated into the `Content` model, and are available +in the `Renderer` extensions. + +This element is a bit complex, so you can read more about how to use it [in a separate section](extra.md). |