diff options
| -rw-r--r-- | README.md | 81 |
1 files changed, 80 insertions, 1 deletions
@@ -1,4 +1,83 @@ dokka ===== -Documentation Engine for Kotlin +Dokka is documentation engine for Kotlin, performing the same function as javadoc for Java. + +**NOTE**: It is work in progress both on compiler side and this tool. Do not base your business on it. Yet. + +Documentation Model +===== + +Dokka uses Kotlin-as-a-service technology to build `code model`, then processes it into `documentation model`. +`Documentation model` is graph of items describing code elements such as classes, packages, functions, etc. + +Each node has semantic attached, e.g. Value:name -> Type:String means that some value `name` is of type `String`. + +Each reference between nodes also has semantic attached, and there are three of them: + +1. Member - reference means that target is member of the source, form tree. +2. Detail - reference means that target describes source in more details, form tree. +3. Link - any link to any other node, free form. + +Member & Detail has reverse Owner reference, while Link's reference is also Link. + +Nodes that are Details of other nodes cannot have Members. + +Rendering Docs +==== +When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services: + +* FormatService -- represents output format +* LocationService -- represents folder and file layout +* SignatureGenerator -- represents target language by generating class/function/package signatures from model + +Basically, given the `documentation` as a model, we do this: + +```kotlin + val signatureGenerator = KotlinSignatureGenerator() + val locationService = FoldersLocationService(arguments.outputDir) + val markdown = JekyllFormatService(locationService, signatureGenerator) + val generator = FileGenerator(signatureGenerator, locationService, markdown) + generator.generate(documentation) +``` + +Roadmap +===== + +#### Formats + +Documentation can be generated in various mark-up formats. + +* Text -- plain text format +* HTML -- html format, suitable for local browsing +* MD -- markdown format, and optional Jekyll extension for your GitHub pages + +#### Locations + +Place documentation in different file structure. All links are relative regardless of structure. + +* Single File -- all documentation is placed in the single file +* Single Folder -- all documentation is in same folder, files are generated per entity +* Folder Tree -- folders are mirroring package/class/method structure, files are leaf elements + +#### Languages + +Output symbol declarations in different languages. + +* Kotlin +* Java +* JavaScript + +#### Features + +* Support JavaDoc in Java and Kotlin files +* Support KDoc in Kotlin files + +#### KDoc + +KDoc is a flavour of markdown with symbol processing extensions. + +* \[name\] - link to `name` (markdown style) +* $name - link to `name` (Kotlin string interpolation style), or ${java.lang.String} for longer references +* $name: - named section, optionally bound to symbol `name`, e.g. param doc +* !{reference} -- include content of a file or symbol denoted by reference, e.g. code example |