Merge pull request #68 from aSemy/fix/kdoc

Tidy KDoc

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/CDATAElement.kt

@@ -3,7 +3,7 @@ package org.redundent.kotlin.xml
 import org.apache.commons.lang3.builder.HashCodeBuilder
 
 /**
- * Similar to a [TextElement] except that the inner text is wrapped inside a <![CDATA[]]> tag.
+ * Similar to a [TextElement] except that the inner text is wrapped inside a `<![CDATA[]]>` tag.
  */
 class CDATAElement internal constructor(text: String) : TextElement(text) {
 	override fun renderedText(printOptions: PrintOptions): String {

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/Comment.kt

@@ -1,8 +1,9 @@
 package org.redundent.kotlin.xml
 
 /**
- * Similar to a [TextElement] except that the inner text is wrapped inside a comment tag <!-- -->
- * Note that "--" will be replaced with "&#45;&#45;"
+ * Similar to a [TextElement] except that the inner text is wrapped inside a comment tag `<!-- -->`.
+ *
+ * Note that `--` will be replaced with `&#45;&#45;`.
  */
 class Comment internal constructor(val text: String) : Element {
 	override fun render(builder: Appendable, indent: String, printOptions: PrintOptions) {

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/Element.kt

@@ -6,7 +6,7 @@ package org.redundent.kotlin.xml
  */
 interface Element {
 	/**
-	 * This method handles creating the xml. Used internally
+	 * This method handles creating the XML. Used internally.
 	 */
 	fun render(builder: Appendable, indent: String, printOptions: PrintOptions)
 }

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/Namespace.kt

@@ -1,15 +1,15 @@
 package org.redundent.kotlin.xml
 
 /**
- * Represents an xml namespace (xmlns).
+ * Represents an xml namespace (`xmlns`).
  */
 data class Namespace(
 	/**
-	 * The name or prefix of the namespace
+	 * The name or prefix of the namespace.
 	 */
 	val name: String,
 	/**
-	 * The value/uri/url of the namespace
+	 * The value/uri/url of the namespace.
 	 */
 	val value: String
 ) {

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/Node.kt

@@ -38,7 +38,7 @@ open class Node(val nodeName: String) : Element {
 		get() = LinkedHashSet(_namespaces)
 
 	/**
-	 * The default xmlns for the document. To add other namespaces, use the [namespace] method
+	 * The default `xmlns` for the document. To add other namespaces, use the [namespace] method
 	 */
 	var xmlns: String?
 		get() = namespaces.firstOrNull(Namespace::isDefault)?.value
@@ -51,14 +51,14 @@ open class Node(val nodeName: String) : Element {
 		}
 
 	/**
-	 * Whether to include the xml prolog, i.e. <?xml version="1.0" encoding="UTS-8"?>
+	 * Whether to include the xml prolog, i.e. `<?xml version="1.0" encoding="UTS-8"?>`.
 	 *
-	 * <p>NOTE: this only applies to the root element. It is ignored an all children
+	 * NOTE: this only applies to the root element. It is ignored an all children.
 	 */
 	var includeXmlProlog = false
 
 	/**
-	 * Sets the encoding on the document. Setting this value will set [includeXmlProlog] to true
+	 * Sets the encoding on the document. Setting this value will set [includeXmlProlog] to `true`.
 	 */
 	var encoding: String = Charsets.UTF_8.name()
 		set(value) {
@@ -122,8 +122,8 @@ open class Node(val nodeName: String) : Element {
 	}
 
 	/**
-	 * Allows for easy access of adding/updating this node's attributes. Setting the value of an attribute to "null"
-	 * will remove the attribute .
+	 * Allows for easy access of adding/updating this node's attributes.
+	 * Setting the value of an attribute to `null` will remove the attribute.
 	 *
 	 * ```
 	 * element["key"] = "value"
@@ -242,14 +242,14 @@ open class Node(val nodeName: String) : Element {
 		if (!printOptions.pretty) { "" } else { "$indent${printOptions.indent}" }
 
 	/**
-	 * Get the xml representation of this object with prettyFormat = true
+	 * Get the XML representation of this object with `prettyFormat = true`.
 	 */
 	override fun toString() = toString(prettyFormat = true)
 
 	/**
-	 * Get the xml representation of this object
+	 * Get the XML representation of this object.
 	 *
-	 * @param [prettyFormat] true to format the xml with newlines and tabs; otherwise no formatting
+	 * @param [prettyFormat] true to format the XML with newlines and tabs; otherwise no formatting
 	 */
 	fun toString(prettyFormat: Boolean): String = toString(PrintOptions(pretty = prettyFormat))
 
@@ -298,7 +298,7 @@ open class Node(val nodeName: String) : Element {
 	 * comment("my comment")
 	 * ```
 	 *
-	 * @param text The text of the comment. This text will be rendered unescaped except for replace "--" with "&#45;&#45;"
+	 * @param text The text of the comment. This text will be rendered unescaped except for replace `--` with `&#45;&#45;`
 	 */
 	fun comment(text: String) {
 		_children.add(Comment(text))
@@ -308,7 +308,7 @@ open class Node(val nodeName: String) : Element {
 	 * Adds a basic element with the specific name to the parent.
 	 * ```
 	 * element("url") {
-	 *     ...
+	 *     // ...
 	 * }
 	 * ```
 	 *
@@ -364,7 +364,7 @@ open class Node(val nodeName: String) : Element {
 	 * allows you to specify optional attributes and content
 	 * ```
 	 * "url"("key" to "value") {
-	 *    ...
+	 *    // ...
 	 * }
 	 * ```
 	 *
@@ -381,7 +381,7 @@ open class Node(val nodeName: String) : Element {
 	 * allows you to specify the namespace of the element as well as optional attributes and content
 	 * ```
 	 * "url"(ns, "key" to "value") {
-	 *     ...
+	 *     // ...
 	 * }
 	 * ```
 	 *
@@ -484,8 +484,6 @@ open class Node(val nodeName: String) : Element {
 
 	/**
 	 * Adds a set of attributes to the current element.
-	 * @see [attribute]
-	 *
 	 * ```
 	 * "url" {
 	 *     attributes(
@@ -494,17 +492,15 @@ open class Node(val nodeName: String) : Element {
 	 *     )
 	 * }
 	 * ```
-	 *
 	 * @param attrs Collection of the attributes to apply to this element.
+	 * @see attribute
 	 */
 	fun attributes(vararg attrs: Pair<String, Any>) {
 		attrs.forEach { attribute(it.first, it.second) }
 	}
 
 	/**
 	 * Adds a set of attributes to the current element.
-	 * @see [attribute]
-	 *
 	 * ```
 	 * "url" {
 	 *     attributes(
@@ -515,6 +511,7 @@ open class Node(val nodeName: String) : Element {
 	 * ```
 	 *
 	 * @param attrs Collection of the attributes to apply to this element.
+	 * @see attribute
 	 */
 	fun attributes(vararg attrs: Attribute) {
 		for (attr in attrs) {
@@ -527,7 +524,6 @@ open class Node(val nodeName: String) : Element {
 
 	/**
 	 * Adds a set of attributes to the current element.
-	 * @see [attribute]
 	 *
 	 * ```
 	 * "url" {
@@ -541,6 +537,7 @@ open class Node(val nodeName: String) : Element {
 	 * @param namespace Optional namespace object to use to build the name of the attribute. Note this does NOT declare
 	 * the namespace. It simply uses it to build the attribute name(s).
 	 * @param attrs Collection of the attributes to apply to this element.
+	 * @see attribute
 	 */
 	fun attributes(namespace: Namespace, vararg attrs: Pair<String, Any>) {
 		attrs.forEach { attribute(it.first, it.second, namespace) }
@@ -771,7 +768,7 @@ open class Node(val nodeName: String) : Element {
 		addElementsBefore(listOf(*elements), before)
 
 	/**
-	 * Removes a node from the node
+	 * Removes a node from the node.
 	 * @param node The node to remove
 	 *
 	 * @throws IllegalArgumentException If [node] can't be found
@@ -783,7 +780,7 @@ open class Node(val nodeName: String) : Element {
 	fun removeNode(node: Node) = removeElement(node)
 
 	/**
-	 * Removes an element from the node
+	 * Removes an element from the node.
 	 * @param element The element to remove
 	 *
 	 * @throws IllegalArgumentException If [element] can't be found
@@ -794,15 +791,15 @@ open class Node(val nodeName: String) : Element {
 	}
 
 	/**
-	 * Removes the elements from the node
+	 * Removes the elements from the node.
 	 * @param elements The elements to remove
 	 *
 	 * @throws IllegalArgumentException If any [elements] can't be found
 	 */
 	fun removeElements(vararg elements: Element) = removeElements(listOf(*elements))
 
 	/**
-	 * Removes the elements from the node
+	 * Removes the elements from the node.
 	 * @param elements The elements to remove
 	 *
 	 * @throws IllegalArgumentException If any [elements] can't be found
@@ -819,7 +816,7 @@ open class Node(val nodeName: String) : Element {
 	}
 
 	/**
-	 * Replaces a node with a different node
+	 * Replaces a node with a different node.
 	 * @param existing The existing node to replace
 	 * @param newNode The node to replace [existing] with
 	 *
@@ -832,7 +829,7 @@ open class Node(val nodeName: String) : Element {
 	fun replaceNode(existing: Node, newNode: Node) = replaceElement(existing, newNode)
 
 	/**
-	 * Replaces an element with a different element
+	 * Replaces an element with a different element.
 	 * @param existing The existing element to replace
 	 * @param newElement The element to replace [existing] with
 	 *

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/PrintOptions.kt

@@ -41,11 +41,9 @@ class PrintOptions(
 	/**
 	 * Whether to use escaped character or character reference
 	 *
-	 * if false "'" becomes '
+	 * If false: `'` becomes `'`
 	 *
-	 * vs
-	 *
-	 * if true "'" becomes '
+	 * If `true`: `'` becomes `'`
 	 */
 	val useCharacterReference: Boolean = false,
 

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/ProcessingInstructionElement.kt

@@ -3,7 +3,7 @@ package org.redundent.kotlin.xml
 import org.apache.commons.lang3.builder.HashCodeBuilder
 
 /**
- * Similar to a [TextElement] except that the inner text is wrapped inside <??> tag.
+ * Similar to a [TextElement] except that the inner text is wrapped inside `<??>` tag.
  */
 class ProcessingInstructionElement internal constructor(text: String, private val attributes: Map<String, String>) :
 	TextElement(text) {

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/TextElement.kt

@@ -2,8 +2,11 @@ package org.redundent.kotlin.xml
 
 /**
  * An element type that has some text in it.
+ *
  * For example:
+ * ```xml
  * <loc>http://blog.redundent.org</loc>
+ * ```
  */
 open class TextElement internal constructor(val text: String, private val unsafe: Boolean = false) : Element {
 	private fun isEmpty() = text.trim('\n', '\r').isBlank()

kotlin-xml-builder/src/main/kotlin/org/redundent/kotlin/xml/XmlBuilder.kt

@@ -11,14 +11,14 @@ import org.w3c.dom.Node as W3CNode
 internal fun getLineEnding(printOptions: PrintOptions) = if (printOptions.pretty) System.lineSeparator() else ""
 
 /**
- * Creates a new xml document with the specified root element name
+ * Creates a new XML document with the specified root element name.
  *
  * @param root The root element name
- * @param encoding The encoding to use for the xml prolog
+ * @param encoding The encoding to use for the XML prolog
  * @param version The XML specification version to use for the xml prolog and attribute encoding
- * @param namespace Optional namespace object to use to build the name of the attribute. This will also add an xmlns
+ * @param namespace Optional namespace object to use to build the name of the attribute. This will also add an `xmlns`
  * attribute for this value
- * @param init The block that defines the content of the xml
+ * @param init The block that defines the content of the XML
  */
 fun xml(
 	root: String,
@@ -47,10 +47,10 @@ fun xml(
 }
 
 /**
- * Creates a new xml document with the specified root element name
+ * Creates a new XML document with the specified root element name.
  *
  * @param name The name of the element
- * @param init The block that defines the content of the xml
+ * @param init The block that defines the content of the XML
  */
 fun node(name: String, namespace: Namespace? = null, init: (Node.() -> Unit)? = null): Node {
 	val node = Node(buildName(name, namespace))