add comments and update to cangjie 1.0.5

Author: causerp

.github/workflows/ci.yml

@@ -12,18 +12,18 @@ jobs:
           - os: ubuntu-latest
             cangjie_version: 1.0.0
           - os: ubuntu-latest
-            cangjie_version: 1.0.4
+            cangjie_version: 1.0.5
           - os: windows-latest
-            cangjie_version: 1.0.4
+            cangjie_version: 1.0.5
           - os: macos-latest
-            cangjie_version: 1.0.4
+            cangjie_version: 1.0.5
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Setup Cangjie
-        uses: Zxilly/setup-cangjie@v2.1.0
+        uses: Zxilly/setup-cangjie@d932a790bbb53ff47ead0609829d91a1e831a440
         with:
           channel: lts
           version: ${{ matrix.cangjie_version }}

License.txt

@@ -1,6 +1,6 @@
 MIT No Attribution
 
-Copyright (c) 2025 causerp
+Copyright (c) 2026 causerp
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

cjpm.toml

@@ -2,7 +2,7 @@
   cjc-version = "1.0.0"
   name = "cenum"
   description = "C enum macro"
-  version = "1.1.1"
+  version = "1.1.2"
   target-dir = ""
   src-dir = ""
   output-type = "dynamic"

src/common.cj

@@ -6,6 +6,19 @@ import std.math.abs
 
 // cjlint-ignore -start !G.FUN.01 function should be less than 50 lines of code
 
+/**
+ * @brief Generates the beginning block of the enum struct.
+ *
+ * Constructs the struct definition, constructors, and operator overloads
+ * based on the provided parameters.
+ *
+ * @param visibility The access modifier token (e.g., `public`, `private`).
+ * @param name The name of the enum struct.
+ * @param valueType The underlying integer type token (e.g., `Int32`, `UInt8`).
+ * @param addFlagOps If `true`, adds bitwise operators for flag enums.
+ * @param ffi_c If `true`, generates a C-compatible struct (without protocols like Hashable).
+ * @return A `Tokens` object containing the generated struct definition header.
+ */
 private func enumBlockBegin(visibility: Token, name: Token, valueType: Token, addFlagOps!: Bool, ffi_c!: Bool): Tokens {
     let block = quote()
     if (ffi_c) {
@@ -95,6 +108,16 @@ private func enumBlockBegin(visibility: Token, name: Token, valueType: Token, ad
     return block
 }
 
+/**
+ * @brief Parses the value assigned to an enum member.
+ *
+ * Analyzes the tokens following an identifier to determine the enum's value.
+ * If no assignment is found, it uses the `currentEnumIndex`.
+ *
+ * @param currentEnumIndex The current auto-incremented index.
+ * @param tokenIt An iterator over the tokens.
+ * @return A tuple containing the tokens representing the value and the new index.
+ */
 private func parseEnumValue(currentEnumIndex: Int32, tokenIt: Iterator<Token>): (Tokens, Int32) {
     let valueTokens = quote()
     var hasAssign = false
@@ -130,6 +153,19 @@ private const ERROR_MSG = "Invalid CEnum syntax"
 private const ERROR_HINT = "Syntax: CEnum[<Private|public|..> <Identifier> <type>]()\n" +
     "Example: CEnum[Seek](...),  CEnum[public Seek](...), CEnum[public Seek UInt32](...)"
 
+/**
+ * @brief Generates the full definition of a C-style enum.
+ *
+ * This is the core logic function that processes attribute and input tokens
+ * to produce the enum struct and its static members.
+ *
+ * @param attrTokens Tokens containing visibility, name, and type information.
+ * @param inputTokens Tokens containing the enum member identifiers.
+ * @param flagEnum If `true`, treats the enum as a bitfield (doubling values for auto-increment).
+ * @param startValue The starting value for the first enum member.
+ * @param ffi_c If `true`, generates a C-compatible struct.
+ * @return The generated `Tokens` representing the complete enum definition.
+ */
 func makeEnum(attrTokens: Tokens, inputTokens: Tokens, flagEnum!: Bool = false, startValue!: Int32 = 0,
     ffi_c!: Bool = false): Tokens {
     var visibility = Token(INTERNAL)

src/enums.cj

@@ -2,34 +2,106 @@ macro package cenum
 
 import std.ast.Tokens
 
+/**
+ * @brief Defines a standard enumeration.
+ *
+ * Generates an enum struct that implements `Hashable` and `Comparable`.
+ * Values auto-increment starting from 0.
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro Enum(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens)
 }
 
+/**
+ * @brief Defines a C-compatible standard enumeration.
+ *
+ * Generates a C-compatible struct (`@C`) for use with FFI.
+ * Values auto-increment starting from 0.
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro CEnum(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, ffi_c: true)
 }
 
+/**
+ * @brief Defines a flag (bitfield) enumeration.
+ *
+ * Generates an enum struct with bitwise operators (`|`, `&`, `^`, etc.).
+ * Values auto-increment using bit shifting starting from 0 (0, 1, 2, 4, ...).
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro FlagEnum(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true)
 }
 
+/**
+ * @brief Defines a flag (bitfield) enumeration starting at 0.
+ *
+ * Similar to `FlagEnum`, explicitly starts the sequence at 0.
+ * Values: 0, 1, 2, 4, ...
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro FlagEnum0(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true)
 }
 
+/**
+ * @brief Defines a flag (bitfield) enumeration starting at 1.
+ *
+ * Generates a flag enum where the first value is 1.
+ * Values: 1, 2, 4, 8, ...
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro FlagEnum1(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true, startValue: 1)
 }
 
+/**
+ * @brief Defines a C-compatible flag (bitfield) enumeration.
+ *
+ * Generates a C-compatible struct (`@C`) with bitwise operators.
+ * Values auto-increment starting from 0.
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro CFlagEnum(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true, ffi_c: true)
 }
 
+/**
+ * @brief Defines a C-compatible flag (bitfield) enumeration starting at 0.
+ *
+ * Generates a C-compatible struct (`@C`) with bitwise operators.
+ * Values: 0, 1, 2, 4, ...
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro CFlagEnum0(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true, ffi_c: true)
 }
 
+/**
+ * @brief Defines a C-compatible flag (bitfield) enumeration starting at 1.
+ *
+ * Generates a C-compatible struct (`@C`) with bitwise operators.
+ * Values: 1, 2, 4, 8, ...
+ *
+ * @param attrTokens Tokens specifying visibility, name, and optional type.
+ * @param inputTokens Tokens specifying the enum members.
+ */
 public macro CFlagEnum1(attrTokens: Tokens, inputTokens: Tokens) {
     makeEnum(attrTokens, inputTokens, flagEnum: true, startValue: 1, ffi_c: true)
 }