/*
 * Copyright (c) 杭州颉创科技有限公司 2025. All rights reserved.
 * This source file is licensed under the MIT License found in the
 * LICENSE file in the root directory of this source tree.
 */

package simcu::simapi.annotations

/**
 * @brief 为控制器或动作提供 API 文档元数据（对齐 C# [SimApiDoc] 特性）。
 *
 * 用法：
 *   @SimApiDoc[tags: "登录", summary: "用户登录相关接口"]
 *   @SimApiDoc[tags: "认证", summary: "后台登录", groupNames: "admin"]
 *   @SimApiDoc[tags: "公共", groupNames: "api,admin"]   // 同时出现在 api 和 admin 文档
 *   @SimApiDoc[tags: "公共", groupNames: "*"]            // 出现在所有文档
 */
@Annotation[target: [MemberFunction, Type, MemberProperty, MemberVariable, Parameter]]
public class SimApiDoc {
    /**
     * @brief API 名称。
     */
    public let name: ?String
    /**
     * @brief 当前 API 是否应被忽略。
     */
    public let ignore: Bool
    /**
     * @brief API 摘要信息。
     */
    public let summary: ?String
    /**
     * @brief API 分组名称（逗号分隔，如 "api,admin"）；"*" 表示出现在所有文档；空串表示未分组（仅进默认文档）。
     */
    public let groupNames: String
    /**
     * @brief API 描述信息。
     */
    public let description: ?String
    /**
     * @brief API 标签字符串。
     */
    public let tags: ?String

    /**
     * @brief 创建 SimApiDoc 注解实例。
     * @param name API 名称。
     * @param ignore 是否忽略当前 API。
     * @param summary API 摘要。
     * @param groupNames API 分组名称（逗号分隔，如 "api,admin"）；"*" 表示出现在所有文档；空串表示未分组（仅进默认文档）。
     * @param description API 描述。
     * @param tags API 标签字符串。
     */
    public const init(name!: ?String = None, ignore!: Bool = false, summary!: ?String = None, groupNames!: String = "",
        description!: ?String = None, tags!: ?String = None) {
        this.tags = tags
        this.name = name
        this.ignore = ignore
        this.summary = summary
        this.groupNames = groupNames
        this.description = description
    }
}