Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

KDoc is the default documentation language for Kotlin, combining JavaDoc’s block tag syntax with Markdown for inline formatting. It is parsed by the Dokka engine to generate static API reference documentation. A KDoc comment is enclosed within /** and */. The parser strictly interprets the internal structure: the first paragraph serves as the summary of the element, subsequent paragraphs provide the detailed description, and the comment concludes with specific block tags. 
/**
 * Calculates the cross product of two 3D vectors.
 *
 * This function utilizes standard matrix determinant expansion to compute
 * the orthogonal vector. It supports **Markdown** for formatting, such as
 * `inline code` or lists.
 *
 * @param v1 The first [Vector3D] operand.
 * @param v2 The second [Vector3D] operand.
 * @return A new [Vector3D] representing the cross product.
 * @throws IllegalArgumentException if either vector has a magnitude of zero.
 * @see Vector3D.dotProduct
 */
fun crossProduct(v1: Vector3D, v2: Vector3D): Vector3D {
    TODO("Implementation pending")
}

​
Element Linking

Unlike JavaDoc, which relies on the {@link} syntax, KDoc uses standard Markdown link syntax with square brackets to reference other code elements. The compiler resolves these references based on the current scope. 
/**
 * Dispatches the event to the [EventListener.onEvent] callback.
 * To use a custom dispatcher, see [com.example.core.Dispatcher].
 */

​
Standard Block Tags

KDoc supports a specific set of block tags to document structural components of Kotlin code.
  • @param <name>: Documents a value parameter of a function or a type parameter of a class/function.
  • @return: Documents the return value of a function.
  • @constructor: Documents the primary constructor of a class.
  • @receiver: Documents the receiver type of an extension function or extension property.
  • @property <name>: Documents a specific property of a class. This is often used to document properties declared directly in the primary constructor.
  • @throws <class> / @exception <class>: Documents an exception that can be thrown by a method.
  • @sample <identifier>: Embeds the body of the specified function into the generated documentation to demonstrate usage. The identifier must resolve to a valid Kotlin function.
  • @see <identifier>: Adds a reference link to the “See Also” block of the generated documentation.
  • @author: Specifies the author of the element.
  • @since: Specifies the version in which the element was introduced.
  • @suppress: Excludes the element from the generated documentation, even if the element is otherwise visible (e.g., public API).

​
Deprecation Handling

A critical structural difference between KDoc and JavaDoc is that KDoc does not support the @deprecated tag. To mark an element as deprecated and document the deprecation reason, developers must apply Kotlin’s built-in @Deprecated annotation directly to the code element. The documentation engine automatically extracts and formats the message provided in the annotation. 
/**
 * Processes the data payload.
 */
@Deprecated("Use processPayloadAsync() instead for non-blocking execution.")
fun processPayload(data: ByteArray) {
    // Implementation
}

​
Syntax Specifics for Kotlin Constructs

Because Kotlin’s syntax differs from Java, KDoc provides specialized handling for Kotlin-specific features: Extension Functions: The @receiver tag is uniquely designed to document the instance an extension function operates on. 
/**
 * Reverses the characters in the string while preserving case.
 *
 * @receiver The original string to be manipulated.
 * @return The reversed string.
 */
fun String.reversePreservingCase(): String {
    TODO("Implementation pending")
}
Primary Constructors and Properties: Instead of writing separate KDoc blocks for the class, the primary constructor, and its properties, KDoc allows documenting them all within the class-level comment using @property and @param. 
/**
 * Represents a network configuration.
 *
 * @property host The IP address or hostname of the server.
 * @property port The port number to bind to.
 * @constructor Creates a new configuration with the specified host and port.
 */
class NetworkConfig(val host: String, val port: Int)
Master Kotlin with Deep Grasping Methodology!Learn More