Ghi chú (Comments) và KDoc trong Kotlin

fun main() {
    // Khai báo biến lưu trữ tên người dùng
    val userName = "Bumbii"
    
    val age = 25  // Tuổi của người dùng
    
    println("Xin chào, $userName!")  // In ra lời chào
}

/*
 * Chương trình tính toán BMI
 * Tác giả: Bumbii Academy
 * Phiên bản: 1.0
 */
fun main() {
    val weight = 70.0
    val height = 1.75
    
    /* 
       Công thức BMI:
       BMI = cân nặng (kg) / chiều cao² (m)
    */
    val bmi = weight / (height * height)
    
    println("BMI của bạn: $bmi")
}

/*
 * Đây là comment ngoài
 * /* Đây là comment lồng bên trong */
 * Vẫn trong comment ngoài
 */

/**
 * Tính tổng hai số nguyên.
 *
 * @param a Số nguyên thứ nhất
 * @param b Số nguyên thứ hai
 * @return Tổng của a và b
 */
fun sum(a: Int, b: Int): Int {
    return a + b
}

/**
 * Đại diện cho một người dùng trong hệ thống.
 *
 * Class này chứa thông tin cơ bản của người dùng bao gồm
 * họ tên và tuổi. Có thể sử dụng để hiển thị thông tin
 * hoặc xác thực tuổi.
 *
 * @property name Họ và tên đầy đủ của người dùng
 * @property age Tuổi của người dùng (phải >= 0)
 * @constructor Tạo một User mới với tên và tuổi
 *
 * @sample
 * ```
 * val user = User("Bumbii", 25)
 * println(user.isAdult()) // true
 * ```
 */
class User(val name: String, val age: Int) {
    
    /**
     * Kiểm tra xem người dùng đã đủ 18 tuổi chưa.
     *
     * @return `true` nếu tuổi >= 18, ngược lại `false`
     */
    fun isAdult(): Boolean = age >= 18
}

/**
 * Xử lý chuỗi JSON.
 *
 * ## Tính năng
 * - Parse JSON string thành object
 * - Validate format
 * - Handle errors gracefully
 *
 * ## Ví dụ
 * ```kotlin
 * val result = parseJson("""{"name": "Bumbii"}""")
 * ```
 *
 * **Lưu ý:** Hàm này có thể throw exception nếu JSON không hợp lệ.
 *
 * @param jsonString Chuỗi JSON cần parse
 * @return Object đã được parse
 * @throws JsonParseException Khi chuỗi không phải JSON hợp lệ
 */
fun parseJson(jsonString: String): Any {
    // Implementation
}

/**
 * Tạo một [User] mới từ dữ liệu JSON.
 *
 * Sử dụng [parseJson] để xử lý chuỗi đầu vào.
 *
 * @see User
 * @see parseJson
 */
fun createUserFromJson(json: String): User {
    // Implementation
}

/**
 * TODO: Thêm KDoc cho class này
 */
class Calculator {
    
    /**
     * TODO: Thêm KDoc cho hàm này
     */
    fun add(a: Double, b: Double): Double = a + b
    
    /**
     * TODO: Thêm KDoc cho hàm này
     */
    fun divide(a: Double, b: Double): Double {
        if (b == 0.0) throw ArithmeticException("Không thể chia cho 0")
        return a / b
    }
}

/**
 * Máy tính đơn giản hỗ trợ các phép toán cơ bản.
 *
 * Cung cấp các phép toán: cộng, trừ, nhân, chia.
 *
 * @sample
 * ```
 * val calc = Calculator()
 * println(calc.add(10.0, 5.0))     // 15.0
 * println(calc.divide(10.0, 2.0))  // 5.0
 * ```
 */
class Calculator {
    
    /**
     * Cộng hai số thực.
     *
     * @param a Số hạng thứ nhất
     * @param b Số hạng thứ hai
     * @return Tổng của [a] và [b]
     */
    fun add(a: Double, b: Double): Double = a + b
    
    /**
     * Chia hai số thực.
     *
     * @param a Số bị chia
     * @param b Số chia (phải khác 0)
     * @return Kết quả của [a] / [b]
     * @throws ArithmeticException Khi [b] bằng 0
     */
    fun divide(a: Double, b: Double): Double {
        if (b == 0.0) throw ArithmeticException("Không thể chia cho 0")
        return a / b
    }
}

/**
 * Fragment hiển thị danh sách sản phẩm.
 *
 * Sử dụng RecyclerView để hiển thị danh sách.
 * Hỗ trợ pull-to-refresh và infinite scroll.
 *
 * @see ProductAdapter
 * @see ProductViewModel
 */
class ProductListFragment : Fragment() {
    
    /**
     * Làm mới danh sách sản phẩm từ server.
     *
     * Hiển thị loading indicator trong khi fetch data.
     * Nếu có lỗi, hiển thị error message.
     */
    fun refreshProducts() {
        // Implementation
    }
}

// TODO: Thêm validation cho input
fun processInput(input: String) {
    // FIXME: Bug - không xử lý Unicode đúng cách
    val processed = input.trim()
}