- 标准请看帮助文件里的:XML Documentation Comments
- 个人常用
- <summary></summary>:摘要
-
/// <summary> /// 这是摘要 /// </summary>
-
- <remarks></remarks>:描述
-
/// <remarks> /// 这是描述 /// </remarks>
-
- <returns></returns>:返回
-
/// <returns>返回值</returns>
-
- <param name=""></param>:参数的名称和描述
-
/// <param name="变量名">类型</param>
-
- <see cref=""/>:形成类似超链接的效果,字下面有横线,但点了后不会跳转
-
/// <see cref="System.Classes.TPersistentClass"/>
-
- <para></para>:新段落
-
/// aa<para>bb</para>cc
-
- <c></c>:用了这个后,英文看起来字体小了一号
-
/// MyName1 <c>MyName2</c> MyName3
-
- <code></code>:代码段,效果有点像 <para><c></c></para>
-
/// MyName1<code>MyName2</code>MyName3
-
- <summary></summary>:摘要
- 网上抄录的
XML注释分为一级注释(Primary Tags)和二级注释(Secondary Tags),前者可以单独存在,后者必须包含在一级注释内部。
- 一级注释
- <remarks>对类型进行描述,功能类似<summary>,据说建议使用<remarks>
- <summary>对共有类型的类、方法、属性或字段进行注释
- <value>主要用于属性的注释,表示属性的制的含义,可以配合<summary>使用
- <param>用于对方法的参数进行说明,格式:<param name="param_name">value</param>
- <returns>用于定义方法的返回值,对于一个方法,输入///后,会自动添加<summary>、<param>列表和<returns>
- <exception>定义可能抛出的异常,格式:<exception cref="IDNotFoundException">
- <example>用于给出如何使用某个方法、属性或者字段的使用方法
- <permission>涉及方法的访问许可
- <seealso>用于参考某个其它的东东:),也可以通过cref设置属性
- <include>用于指示外部的XML注释
- 二级注释
- <c> or <code>主要用于加入代码段
- <para>的作用类似HTML中的<p>标记符,就是分段
- <pararef>用于引用某个参数
- <see>的作用类似<seealso>,可以指示其它的方法
- <list>用于生成一个列表
- 一级注释
- XML中需要的转义字符
- &(逻辑与) &
- <(小于) <
- >(大于) >
- "(双引号) "
- ‘(单引号) '
- 需要注意的是
- 转义序列各字符间不能有空格
- 转义序列必须以";"结束
- 单独的&不被认为是转义开始
- 区分大小写
- 例子
-
/// <summary> /// 对象池 ( 支持模板 ) /// </summary> /// <remarks> /// 这是一个对像池, 可以池化所有 TObject 对像 ( 支持模板 ) /// <code> /// 用法: /// <para>在一个全局的地方定义: </para> /// <para>var</para> /// <para> Pooler: TObjPool<要收集的类名></para> /// </code> /// <code> /// <para>用到的地方: </para> /// <para>tmpObj := Pooler.LockObj as Txxx;</para> /// <para>if Assigned(tmpObj) then</para> /// <para>try</para> /// <para>finally</para> /// <para> Pooler.UnlockObj(tmpObj);</para> /// <para>end;</para> /// </code> /// <code> /// <para>初始化: </para> /// <para>initialization</para> /// <para> Pooler := TObjPool<要收集的类名>(对象池最大值, 对象池最小值).Create;</para> /// <para>finallization</para> /// <para> Pooler.Free;</para> /// </code> /// </remarks>