Delphi新注释 - marklove

Delphi新注释

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

• 个人常用

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

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

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

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

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

      1. /// <returns>返回值</returns>

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

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

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

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

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

      1. ///  aa<para>bb</para>cc

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

      1. ///  MyName1 <c>MyName2</c> MyName3

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

      1. /// MyName1<code>MyName2</code>MyName3

• 网上抄录的

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

1. 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. 1. &(逻辑与) &amp;
   2. <(小于) &lt;
   3. >(大于) &gt;
   4. "(双引号) &quot;
   5. \'(单引号) &apos;

• 需要注意的是

1. 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>