Revise developer guides documentation (#2523)

3 files changed, 11 insertions, 8 deletions

diff --git a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt b/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
index 5cdeeb40..64d9c76d 100644
--- a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
+++ b/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
@@ -24,6 +24,7 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
         report("Validity check")
         validityCheck(context)
 
+        // Step 1: translate sources into documentables & transform documentables (change internally)
         report("Creating documentation models")
         val modulesFromPlatforms = createDocumentationModels()
 
@@ -31,18 +32,20 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
         val transformedDocumentationBeforeMerge = transformDocumentationModelBeforeMerge(modulesFromPlatforms)
 
         report("Merging documentation models")
-        val documentationModel = mergeDocumentationModels(transformedDocumentationBeforeMerge)
+        val transformedDocumentationAfterMerge = mergeDocumentationModels(transformedDocumentationBeforeMerge)
             ?: exitGenerationGracefully("Nothing to document")
 
         report("Transforming documentation model after merging")
-        val transformedDocumentation = transformDocumentationModelAfterMerge(documentationModel)
+        val transformedDocumentation = transformDocumentationModelAfterMerge(transformedDocumentationAfterMerge)
 
+        // Step 2: Generate pages & transform them (change internally)
         report("Creating pages")
         val pages = createPages(transformedDocumentation)
 
         report("Transforming pages")
         val transformedPages = transformPages(pages)
 
+        // Step 3: Rendering
         report("Rendering")
         render(transformedPages)
 
@@ -54,7 +57,7 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
 
     override val generationName = "documentation for ${context.configuration.moduleName}"
 
-    fun createDocumentationModels() = runBlocking(Dispatchers.Default) {
+    fun createDocumentationModels(): List<DModule> = runBlocking(Dispatchers.Default) {
         context.configuration.sourceSets.parallelMap { sourceSet -> translateSources(sourceSet, context) }.flatten()
             .also { modules -> if (modules.isEmpty()) exitGenerationGracefully("Nothing to document") }
     }
@@ -69,10 +72,10 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
     fun transformDocumentationModelAfterMerge(documentationModel: DModule) =
         context[CoreExtensions.documentableTransformer].fold(documentationModel) { acc, t -> t(acc, context) }
 
-    fun createPages(transformedDocumentation: DModule) =
+    fun createPages(transformedDocumentation: DModule): RootPageNode =
         context.single(CoreExtensions.documentableToPageTranslator).invoke(transformedDocumentation)
 
-    fun transformPages(pages: RootPageNode) =
+    fun transformPages(pages: RootPageNode): RootPageNode =
         context[CoreExtensions.pageTransformer].fold(pages) { acc, t -> t(acc) }
 
     fun render(transformedPages: RootPageNode) {
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
index a7ba81ba..2ec4fd7c 100644
--- a/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
+++ b/plugins/base/src/main/resources/dokka/templates/includes/header.ftl
@@ -12,7 +12,7 @@
         </@template_cmd>
     </div>
     <div>
-        <#-- This can be handled by a versioning plugin -->
+        <#-- This can be handled by the versioning plugin -->
         <@version/>
     </div>
     <div class="pull-right d-flex">
@@ -21,4 +21,4 @@
         <div id="searchBar"></div>
     </div>
 </div>
-</#macro>
\ No newline at end of file
+</#macro>
diff --git a/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
index f897c104..7cab4582 100644
--- a/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
+++ b/plugins/base/src/main/resources/dokka/templates/includes/page_metadata.ftl
@@ -3,4 +3,4 @@
     <@template_cmd name="pathToRoot">
     <link href="${pathToRoot}images/logo-icon.svg" rel="icon" type="image/svg">
     </@template_cmd>
-</#macro>
\ No newline at end of file
+</#macro>