Delphi新注释

---

• 标准请看帮助文件里的：XML Documentation Comments

---

• 个人常用

  1. <summary></summary>：摘要

     /// <summary>/// 这是摘要/// </summary>

  2. <remarks></remarks>：描述

     /// <remarks>/// 这是描述/// </remarks>

  3. <returns></returns>：返回

     /// <returns>返回值</returns>

  4. <param name=""></param>：参数的名称和描述

     /// <param name="变量名">类型</param>

  5. <see cref=""/>：形成类似超链接的效果，字下面有横线，但点了后不会跳转

     /// <see cref="System.Classes.TPersistentClass"/>

  6. <para></para>：新段落

     ///  aa<para>bb</para>cc

  7. <c></c>：用了这个后，英文看起来字体小了一号

     ///  MyName1 <c>MyName2</c> MyName3

  8. <code></code>：代码段，效果有点像 <para><c></c></para>

     /// MyName1<code>MyName2</code>MyName3

---

• 网上抄录的

  XML注释分为一级注释（Primary Tags）和二级注释（Secondary Tags），前者可以单独存在，后者必须包含在一级注释内部。

  1. 一级注释

         1. `<remarks>对类型进行描述，功能类似<summary>,据说建议使用<remarks>`    2. `<summary>对共有类型的类、方法、属性或字段进行注释`    3. `<value>主要用于属性的注释，表示属性的制的含义，可以配合<summary>使用`    4. `<param>用于对方法的参数进行说明，格式：<param name="param_name">value</param>`    5. `<returns>用于定义方法的返回值，对于一个方法，输入///后，会自动添加<summary>、<param>列表和<returns>`    6. `<exception>定义可能抛出的异常，格式：<exception cref="IDNotFoundException">`    7. `<example>用于给出如何使用某个方法、属性或者字段的使用方法`    8. `<permission>涉及方法的访问许可`    9. `<seealso>用于参考某个其它的东东：），也可以通过cref设置属性`    10. `<include>用于指示外部的XML注释`

  2. 二级注释

         1. `<c> or <code>主要用于加入代码段`    2. `<para>的作用类似HTML中的<p>标记符，就是分段`    3. `<pararef>用于引用某个参数`    4. `<see>的作用类似<seealso>,可以指示其它的方法`    5. `<list>用于生成一个列表`

---

• XML中需要的转义字符

  1. &(逻辑与) &
  2. <(小于) &lt;
  3. >(大于) >
  4. "(双引号) "
  5. '(单引号) '

---

• 需要注意的是

  1. 转义序列各字符间不能有空格
  2. 转义序列必须以”;”结束
  3. 单独的&不被认为是转义开始
  4. 区分大小写

---

• 例子

/// <summary>/// 对象池 ( 支持模板 )/// </summary>/// <remarks>/// 这是一个对像池, 可以池化所有 TObject 对像 ( 支持模板 )/// <code>/// 用法:/// <para>在一个全局的地方定义: </para>/// <para>var</para>/// <para>  Pooler: TObjPool&lt;要收集的类名&gt;</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&lt;要收集的类名&gt;(对象池最大值, 对象池最小值).Create;</para>/// <para>finallization</para>/// <para>  Pooler.Free;</para>/// </code>/// </remarks>

---