feat: better docs

Author: eschizoid

src/main/kotlin/Main.kt

@@ -8,12 +8,17 @@ import org.slf4j.LoggerFactory
 import org.slf4j.bridge.SLF4JBridgeHandler
 
 /**
- * Start sse-server mcp on port 3001.
+ * Main entry point for the MCP GitHub Code Analysis Server application.
  *
- * @param args
- * - "--stdio": Runs an MCP server using standard input/output.
- * - "--sse-server-ktor <port>": Runs an SSE MCP server using Ktor plugin (default if no argument is provided).
- * - "--sse-server <port>": Runs an SSE MCP server with a plain configuration.
+ * This application provides a server that analyzes GitHub repositories using the Model Context Protocol (MCP). It can
+ * operate in different modes: standard I/O mode or Server-Sent Events (SSE) mode using either plain configuration or
+ * Ktor plugin.
+ *
+ * @param args Command-line arguments to determine server behavior:
+ *     - "--stdio": Runs an MCP server using standard input/output.
+ *     - "--sse-server-ktor <port>": Runs an SSE MCP server using Ktor plugin (default if no args provided).
+ *     - "--sse-server <port>": Runs an SSE MCP server with plain configuration. If no port is specified, the value from
+ *       environment variable SERVER_PORT or default 3001 is used.
  */
 fun main(args: Array<String>) {
   SLF4JBridgeHandler.removeHandlersForRootLogger()
@@ -26,16 +31,33 @@ fun main(args: Array<String>) {
     .onFailure { error -> logger.error("Application failed: ${error.message}", error) }
 }
 
-/** Data class representing application command settings */
+/**
+ * Data class representing application command settings.
+ *
+ * @property type The type of server to start (STDIO, SSE_KTOR, SSE_PLAIN).
+ * @property port The port number on which the server will listen (for SSE modes only).
+ */
 data class AppCommand(val type: CommandType, val port: Int)
 
-/** Enum representing possible commands */
+/**
+ * Enum representing the application command type.
+ *
+ * STDIO - Standard input/output mode for the MCP server SSE_KTOR - Server-Sent Events mode using the Ktor plugin
+ * SSE_PLAIN - Server-Sent Events mode using plain configuration UNKNOWN - Unknown or unsupported command
+ */
 enum class CommandType {
   STDIO,
   SSE_KTOR,
   SSE_PLAIN,
   UNKNOWN;
 
+  /**
+   * Converts a command-line argument to the corresponding CommandType.
+   *
+   * @param arg The command-line argument string.
+   * @return The CommandType corresponding to the argument, or SSE_KTOR if null, or UNKNOWN if the argument is not
+   *   recognized.
+   */
   companion object {
     fun fromArg(arg: String?): CommandType =
       when (arg) {
@@ -48,7 +70,15 @@ enum class CommandType {
   }
 }
 
-/** Runs the application with a functional approach */
+/**
+ * Runs the application by parsing arguments, ensuring necessary directories exist, and executing the appropriate server
+ * command.
+ *
+ * @param args Command-line arguments to determine server behavior.
+ * @return Result wrapping Unit, with success if the application runs successfully, or failure with the exception if an
+ *   error occurs.
+ * @throws IOException If required directories cannot be created.
+ */
 fun runApplication(args: Array<String>): Result<Unit> = runCatching {
   val logger = LoggerFactory.getLogger("Main")
 
@@ -64,14 +94,26 @@ fun runApplication(args: Array<String>): Result<Unit> = runCatching {
   executeCommand(command, Server())
 }
 
-/** Parse command line arguments into a structured command */
+/**
+ * Parses command-line arguments into an [AppCommand] object.
+ *
+ * @param args The command-line arguments array.
+ * @param defaultPort The default port to use if not specified in arguments.
+ * @return An AppCommand object containing the parsed command type and port.
+ */
 fun parseArgs(args: Array<String>, defaultPort: Int): AppCommand {
   val commandType = CommandType.fromArg(args.firstOrNull())
   val port = args.getOrNull(1)?.toIntOrNull() ?: defaultPort
   return AppCommand(commandType, port)
 }
 
-/** Ensures both application directories are properly created with clear error handling */
+/**
+ * Ensures that all required application directories exist, creating them if necessary.
+ *
+ * @param config The application configuration containing directory paths.
+ * @return A list of Results, each containing a Pair of the Path and a Boolean indicating whether the directory was
+ *   newly created (true) or already existed (false).
+ */
 fun ensureApplicationDirectories(config: AppConfig): List<Result<Pair<Path, Boolean>>> {
   val logger = LoggerFactory.getLogger("Main")
 
@@ -89,7 +131,15 @@ fun ensureApplicationDirectories(config: AppConfig): List<Result<Pair<Path, Bool
   return listOf(cloneDirResult, logsDirResult)
 }
 
-/** Creates a directory with its full path, handling all parent directories */
+/**
+ * Creates a directory and all parent directories if they don't exist.
+ *
+ * @param path The Path to the directory to create.
+ * @return Result containing a Pair of the Path and a Boolean indicating whether the directory was newly created (true)
+ *   or already existed (false).
+ * @throws IOException If the path exists but is not a directory, creation fails, or the directory doesn't exist after
+ *   attempted creation.
+ */
 fun createDirectoryWithFullPath(path: Path): Result<Pair<Path, Boolean>> = runCatching {
   val logger: Logger = LoggerFactory.getLogger("Main")
 
@@ -106,7 +156,13 @@ fun createDirectoryWithFullPath(path: Path): Result<Pair<Path, Boolean>> = runCa
   path to true
 }
 
-/** Executes the appropriate server command */
+/**
+ * Executes the appropriate server command based on the provided AppCommand.
+ *
+ * @param command The AppCommand specifying the type of server to start and its port.
+ * @param server The Server instance to use for execution.
+ * @throws IllegalArgumentException If the command type is UNKNOWN.
+ */
 fun executeCommand(command: AppCommand, server: Server) {
   val logger = LoggerFactory.getLogger("Main")
 

src/main/kotlin/mcp/code/analysis/service/CodeAnalyzer.kt

@@ -13,6 +13,7 @@ data class CodeAnalyzer(
   private val binaryDetectionThreshold: Double = 0.05,
   private val logger: Logger = LoggerFactory.getLogger(ModelContextService::class.java),
 ) {
+
   /**
    * Analyzes the structure of a codebase.
    *

src/main/kotlin/mcp/code/analysis/service/GitService.kt

@@ -7,6 +7,7 @@ import org.eclipse.jgit.api.Git
 
 /** Service for interacting with Git repositories. */
 data class GitService(private val config: AppConfig = AppConfig.fromEnv()) {
+
   /**
    * Clones a Git repository to a temporary directory.
    *

src/main/kotlin/mcp/code/analysis/service/ModelContextService.kt

@@ -28,9 +28,7 @@ data class ChatRequest(
 
 @Serializable data class ChatResponse(val message: ChatMessage? = null)
 
-/**
- * Functional service for interacting with the Ollama model API. All dependencies are explicitly injected and immutable.
- */
+/** Service for interacting with the Ollama model API. All dependencies are explicitly injected and immutable. */
 data class ModelContextService(
   private val config: AppConfig = AppConfig.fromEnv(),
   private val httpClient: HttpClient = defaultHttpClient(),

src/main/kotlin/mcp/code/analysis/service/RepositoryAnalysisService.kt

@@ -6,6 +6,7 @@ data class RepositoryAnalysisService(
   private val codeAnalyzer: CodeAnalyzer = CodeAnalyzer(),
   private val modelContextService: ModelContextService = ModelContextService(),
 ) {
+
   /**
    * Analyzes a Git repository and generates insights about its code structure and content.
    *