Ant Design Blazor 组件库文档编写规范指南

Ant Design Blazor 组件库文档编写规范指南

ant-design-blazor 🌈A set of enterprise-class UI components based on Ant Design and Blazor WebAssembly. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-blazor

前言

Ant Design Blazor 是一款基于 Blazor 技术栈的企业级 UI 组件库，其文档系统采用了自动化生成机制。本文将深入解析该组件库的文档编写规范，帮助开发者理解如何为组件编写高质量的文档。

文档生成机制概述

Ant Design Blazor 的文档系统采用了代码与文档自动同步的设计理念。文档内容直接来源于代码中的 XML 注释，通过特定的标记和格式约定，系统能够自动生成结构化的文档页面。这种设计确保了文档与代码实现始终保持一致。

组件文档化基础

文档化属性标记

要为组件生成文档页面，必须使用 Documentation 属性进行标记。该属性包含三个必需参数和多个可选参数：

[Documentation(DocumentationCategory.Components, 
               DocumentationType.DataDisplay, 
               "https://fullUrl.com/to/image.jpg")]

核心参数说明：

1. 分类（Category）：从预定义的枚举中选择，如 Components、Layout 等
2. 类型（Type）：从预定义的枚举中选择，如 DataDisplay、Navigation 等
3. 概述页图片：用于组件概览页面的展示图片

可选参数详解：

• Title：自定义页面标题（同时影响URL）
• Columns：设置演示示例的列数（默认2列）
• Subtitle：页面副标题
• OutputApi：控制是否输出API文档（默认true）

特殊使用场景

对于组合多个组件的页面（如Typography、Layout等），建议：

1. 选择一个合适的组件添加 Documentation 属性
2. 设置 OutputApi = false
3. 使用 <seealso> 标签引用相关组件的API

XML 注释标签详解

核心标签

1. <summary>

   • 用途：组件/页面的主描述
   • 位置：位于页面标题下方、演示示例上方
   • 建议：使用段落(<para>)和列表(<list>)增强可读性

2. <default value="..."/>

   • 自定义标签，用于指定默认值
   • 显示在API表格的"默认值"列
   • 即使默认值由逻辑决定也建议填写

3. 交叉引用标签

   • <see cref="..."/>：行内引用，自动生成链接
   • <seealso cref="..."/>：在API部分添加额外文档

格式化标签

• <para>：段落分隔
• <list type="bullet|number">：创建列表
• <c>：代码样式文本
• HTML标题标签(<h1>-<h6>)：创建章节结构

常见问题(FAQ)集成

添加FAQ的规范

1. 文件位置：

   Demos/Components/[组件名称]/faq.[语言代码].md
   

2. 命名规则：

   • 语言代码示例：en-US、zh-CN
   • 目前不支持自动翻译，需为每种语言提供单独文件

3. 内容格式：

   • 使用标准Markdown语法
   • 建议采用问答形式组织内容

高级文档特性

废弃标记处理

使用 [Obsolete] 特性时：

[Obsolete("改用NewComponent替代，将在v2.0移除")]

• 自动显示废弃警告
• 包含移除版本提示

文档排除规则

以下内容不会出现在文档中：

1. 注入服务([Inject])
2. 级联参数([CascadingParameter])
3. 特殊成员和构造函数
4. 内置方法和Blazor生命周期方法

多语言支持机制

翻译策略

自动翻译内容：

• 摘要标签(<summary>)
• 废弃消息
• API表格标题

保留原文的内容：

• 成员/类名称
• 数据类型
• 默认值文本
• 方法签名

翻译覆盖机制

当自动翻译不准确时，可手动指定翻译：

/// <summary>
/// English description
/// </summary>
/// <summary xml:lang="zh-CN">
/// 中文描述
/// </summary>

翻译服务架构

1. 默认服务：Azure翻译

   • 需要配置API密钥
   • 每月200万字符免费额度

2. 备用服务：Google翻译

   • 请求限制严格
   • 仅作为备选方案

3. 缓存机制：

   • 自动缓存已知翻译
   • 避免重复请求
   • 定期清理未使用的翻译

最佳实践建议

1. 组件文档化：

   • 为每个公开组件添加 Documentation 属性
   • 提供有意义的概述图片

2. API文档：

   • 为所有公共成员编写详细的 <summary>
   • 明确指定 <default> 值
   • 使用 <see> 创建有用的交叉引用

3. 内容组织：

   • 使用 <para> 和 <list> 提高可读性
   • 为复杂组件添加FAQ
   • 考虑多语言用户提供翻译覆盖

4. 维护性：

   • 及时标记废弃成员
   • 保持文档与代码变更同步
   • 利用缓存机制减少翻译开销

通过遵循这些规范，开发者可以确保 Ant Design Blazor 组件库的文档保持高质量、一致性和易用性，为用户提供最佳的使用体验。

ant-design-blazor 🌈A set of enterprise-class UI components based on Ant Design and Blazor WebAssembly. 项目地址: https://gitcode.com/gh_mirrors/an/ant-design-blazor