Improve documentation (and its styling)

Ninja-Squad · Jun 2, 2016 · 2f63842 · 2f63842
1 parent c843205
commit 2f63842
Show file tree

Hide file tree

Showing 6 changed files with 321 additions and 6 deletions.
diff --git a/DbSetup-kotlin/build.gradle b/DbSetup-kotlin/build.gradle
@@ -24,6 +24,14 @@ dependencies {
 dokka {
  inputs.dir 'src/main/kotlin'
  jdkVersion = 8
+ inputs.dir 'config/dokka'
+ doLast {
+ copy {
+ from 'config/dokka'
+ include 'style.css'
+ into outputDirectory
+ }
+ }
 }
 
 task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {

diff --git a/DbSetup-kotlin/config/dokka/style.css b/DbSetup-kotlin/config/dokka/style.css
@@ -0,0 +1,290 @@
+/*
+ * customized style for the generated dokka documentation
+ * fonts are a bit larger, and the width of the first cell of tables is fixed, to make sure everything is
+ * aligned.
+ */
+
+@import url(https://fonts.googleapis.com/css?family=Lato:300italic,700italic,300,700);
+
+body, table {
+ padding:50px;
+ font:18px/1.5 Lato, "Helvetica Neue", Helvetica, Arial, sans-serif;
+ color:#555;
+ font-weight:300;
+}
+
+.keyword {
+ color:black;
+ font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
+ font-size:14px;
+}
+
+.symbol {
+ font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
+ font-size:14px;
+}
+
+.identifier {
+ color: darkblue;
+ font-size:14px;
+ font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ color:#222;
+ margin:0 0 20px;
+}
+
+p, ul, ol, table, pre, dl {
+ margin:0 0 20px;
+}
+
+h1, h2, h3 {
+ line-height:1.1;
+}
+
+h1 {
+ font-size:28px;
+}
+
+h2 {
+ color:#393939;
+}
+
+h3, h4, h5, h6 {
+ color:#494949;
+}
+
+a {
+ color:#258aaf;
+ font-weight:400;
+ text-decoration:none;
+}
+
+a:hover {
+ color: inherit;
+ text-decoration:underline;
+}
+
+a small {
+ font-size:11px;
+ color:#555;
+ margin-top:-0.6em;
+ display:block;
+}
+
+.wrapper {
+ width:860px;
+ margin:0 auto;
+}
+
+blockquote {
+ border-left:1px solid #e5e5e5;
+ margin:0;
+ padding:0 0 0 20px;
+ font-style:italic;
+}
+
+code, pre {
+ font-family:Monaco, Bitstream Vera Sans Mono, Lucida Console, Terminal;
+ color:#333;
+ font-size:14px;
+}
+
+pre {
+ display: block;
+ /*
+ padding:8px 8px;
+ background: #f8f8f8;
+ border-radius:5px;
+ border:1px solid #e5e5e5;
+ */
+ overflow-x: auto;
+}
+
+table {
+ width:100%;
+ border-collapse:collapse;
+}
+
+th, td {
+ text-align:left;
+ vertical-align: top;
+ padding:5px 10px;
+}
+
+th:first-child, td:first-child {
+ width: 180px;
+}
+
+dt {
+ color:#444;
+ font-weight:700;
+}
+
+th {
+ color:#444;
+}
+
+img {
+ max-width:100%;
+}
+
+header {
+ width:270px;
+ float:left;
+ position:fixed;
+}
+
+header ul {
+ list-style:none;
+ height:40px;
+
+ padding:0;
+
+ background: #eee;
+ background: -moz-linear-gradient(top, #f8f8f8 0%, #dddddd 100%);
+ background: -webkit-gradient(linear, left top, left bottom, color-stop(0%,#f8f8f8), color-stop(100%,#dddddd));
+ background: -webkit-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
+ background: -o-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
+ background: -ms-linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
+ background: linear-gradient(top, #f8f8f8 0%,#dddddd 100%);
+
+ border-radius:5px;
+ border:1px solid #d2d2d2;
+ box-shadow:inset #fff 0 1px 0, inset rgba(0,0,0,0.03) 0 -1px 0;
+ width:270px;
+}
+
+header li {
+ width:89px;
+ float:left;
+ border-right:1px solid #d2d2d2;
+ height:40px;
+}
+
+header ul a {
+ line-height:1;
+ font-size:11px;
+ color:#999;
+ display:block;
+ text-align:center;
+ padding-top:6px;
+ height:40px;
+}
+
+strong {
+ color:#222;
+ font-weight:700;
+}
+
+header ul li + li {
+ width:88px;
+ border-left:1px solid #fff;
+}
+
+header ul li + li + li {
+ border-right:none;
+ width:89px;
+}
+
+header ul a strong {
+ font-size:14px;
+ display:block;
+ color:#222;
+}
+
+section {
+ width:500px;
+ float:right;
+ padding-bottom:50px;
+}
+
+small {
+ font-size:13px;
+}
+
+hr {
+ border:0;
+ background:#e5e5e5;
+ height:1px;
+ margin:0 0 20px;
+}
+
+footer {
+ width:270px;
+ float:left;
+ position:fixed;
+ bottom:50px;
+}
+
+@media print, screen and (max-width: 960px) {
+
+ div.wrapper {
+ width:auto;
+ margin:0;
+ }
+
+ header, section, footer {
+ float:none;
+ position:static;
+ width:auto;
+ }
+
+ header {
+ padding-right:320px;
+ }
+
+ section {
+ border:1px solid #e5e5e5;
+ border-width:1px 0;
+ padding:20px 0;
+ margin:0 0 20px;
+ }
+
+ header a small {
+ display:inline;
+ }
+
+ header ul {
+ position:absolute;
+ right:50px;
+ top:52px;
+ }
+}
+
+@media print, screen and (max-width: 720px) {
+ body {
+ word-wrap:break-word;
+ }
+
+ header {
+ padding:0;
+ }
+
+ header ul, header p.view {
+ position:static;
+ }
+
+ pre, code {
+ word-wrap:normal;
+ }
+}
+
+@media print, screen and (max-width: 480px) {
+ body {
+ padding:15px;
+ }
+
+ header ul {
+ display:none;
+ }
+}
+
+@media print {
+ body {
+ padding:0.4in;
+ font-size:14pt;
+ color:#444;
+ }
+}
diff --git a/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/DbSetup.kt b/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/DbSetup.kt
@@ -27,8 +27,9 @@ import com.ninja_squad.dbsetup.DbSetup
 import com.ninja_squad.dbsetup.DbSetupTracker
 
 /**
- * Extension function of DbSetup allowing to launch it with a tracker. This allows launching the setup in an easier way:
- * instead of doing
+ * Extension function of DbSetup allowing to launch it with a tracker. This allows launching the setup in an easier way.
+ *
+ * Instead of doing
  *
  * ```
  * val theSetup = dbSetup {
@@ -45,6 +46,8 @@ import com.ninja_squad.dbsetup.DbSetupTracker
  * }.launchWith(tracker)
  * ```
  *
+ * @param tracker the tracker used to launch the DbSetup, if necessary.
+ *
  * @author JB Nizet
  */
 fun DbSetup.launchWith(tracker: DbSetupTracker) {

diff --git a/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/DbSetupBuilder.kt b/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/DbSetupBuilder.kt
@@ -33,14 +33,12 @@ import com.ninja_squad.dbsetup.operation.Operation
 
 /**
  * A builder allowing to configure a DbSetup from a lambda expression whose receiver type is this builder.
- * The intended usage is to use the dbSetup() top level function.
- *
- * @see dbSetup
+ * The intended usage is to use the [dbSetup] top level function.
  */
 class DbSetupBuilder {
 
  /**
- * The destination of the DbSetup. It's mandatory
+ * The destination of the DbSetup. It is mandatory
  */
  var destination: Destination? = null
 
@@ -53,6 +51,7 @@ class DbSetupBuilder {
 
  /**
  * Adds an Insert operation to the DbSetup, using a lambda expression to configure it.
+ *
  * Example usage:
  *
  * ```
@@ -64,6 +63,9 @@ class DbSetupBuilder {
  * }
  * }
  * ```
+ *
+ * @param table the name of the table to insert into
+ * @param configure the function used to configure the insert.
  */
  inline fun insertInto(table: String, configure: Insert.Builder.() -> Unit) {
  val builder = Insert.into(table)

diff --git a/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/Functions.kt b/DbSetup-kotlin/src/main/kotlin/com/ninja_squad/dbsetup_kotlin/Functions.kt
@@ -46,7 +46,9 @@ import com.ninja_squad.dbsetup.operation.Insert
  * }
  * ```
  *
+ * @param configure the function used to configure the DbSetup
  * @throws IllegalStateException if the destination has not been set by the configure function
+ * @return the created DbSetup
  *
  * @author JB Nizet
  */
@@ -68,6 +70,9 @@ fun dbSetup(configure: DbSetupBuilder.() -> Unit): DbSetup {
  * values(2, "Jane Doe")
  * }
  * ```
+ * @param table the name of the table to insert into
+ * @param configure the function used to configure the Insert
+ * @return the created Insert operation
  *
  * @author JB Nizet
  */