xs:documentation必须嵌套在xs:annotation内且xs:annotation须为schema构造的前两个子元素之一；多语言需用xml:lang标注；内容需转义或cdata包裹；工具支持差异大，需实测验证。
xs:documentation 必须放在 xs:annotation 内部
直接在元素、类型或属性声明里写 xs:documentation 会报错——XML Schema 解析器根本不认这种写法。它只能作为 xs:annotation 的子元素存在，而 xs:annotation 又必须是 schema 构造（比如 xs:element、xs:complexType）的**第一个或第二个子元素**（紧挨着 xs:annotation 或 xs:appinfo）。
常见错误现象：
– 解析时报错 Schematron validation failed 或类似提示
– 工具（如 IntelliJ、Oxygen）标红并提示 “Element 'xs:documentation' cannot appear here”
- 正确位置示例：
<xs:element name="userId"> <xs:annotation> <xs:documentation>用户唯一标识，由系统生成，不可为空</xs:documentation> </xs:annotation> <xs:simpleType> <xs:restriction base="xs:string"> <xs:minLength value="1"/> </xs:restriction> </xs:simpleType> </xs:element> -
xs:annotation不能省略；没有它，xs:documentation就是非法节点 - 同一个 schema 构造下可有多个
xs:annotation，但每个最多含一个ws:documentation（规范允许，但多数工具只读第一个）
多语言注释要用 xml:lang 属性区分
如果文档要支持中英文双语（比如给不同团队看），不能靠两个并列的 xs:documentation——XSD 规范不禁止，但解析行为未定义，多数工具只取第一个。稳妥做法是用 xml:lang 显式标注语言。
- 示例：
<xs:annotation> <xs:documentation xml:lang="zh">订单创建时间，格式为 ISO 8601</xs:documentation> <xs:documentation xml:lang="en">Order creation timestamp in ISO 8601 format</xs:documentation> </xs:annotation>
- 工具兼容性：JAXB 默认忽略
xml:lang，但 Xerces、Saxon 和大多数 IDE 都能识别并按需展示对应语言版本 - 别用
lang（缺少前缀），必须是xml:lang才符合 XML 命名空间规范
注释内容不能含未转义的 、& 字符
很多人把一段代码示例或 HTML 片段直接塞进 xs:documentation，结果 XSD 文件无法被加载——因为 <tag></tag> 被当成标签解析，& 被当成实体起始符。
- 必须转义：
→ <code><，>→>，&→& - 如果注释里要写正则表达式如
[a-z]+，得写成[a-z]+或直接用 CDATA（见下条） - 更省事的方案：用
包裹整段内容，里面无需转义（但注意 CDATA 不能嵌套，且部分老工具对 CDATA 内换行处理不稳定）
IDE 和代码生成工具对 xs:documentation 的支持程度差异大
别假设写了注释就自动出现在 Java 类 Javadoc 或 Swagger UI 里——这取决于你用的工具链和配置。
- JAXB
xjc：默认不生成 Javadoc，需加-Xjavadoc插件，且只认xml:lang="en"的xs:documentation - Apache CXF
wsdl2java：支持，但要求注释在xs:element或xs:complexType级别，字段级注释常被忽略 - Swagger / OpenAPI 转换器（如 xsd2jsonschema）：多数只提取顶层
xs:element的文档，嵌套类型里的xs:documentation很容易丢 - 关键提醒：如果你依赖注释生成 API 文档，务必在实际使用的工具中验证输出，而不是只看 XSD 文件里有没有写
xmllint --schema 或在线 XSD 验证器过一遍，比后期排查生成结果错位省太多力气。 
