Delphi新注释-白红宇

Delphi新注释

阅读量：5796 次

发布时间：2019-06-18

本文共 2137 字，大约阅读时间需要 7 分钟。

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

个人常用

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

<remarks></remarks>：描述

/// 
           
            /// 这是描述///

<returns></returns>：返回

/// 
           
            返回值

<param name=""></param>：参数的名称和描述
1. ```
/// 类型
```

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

<para></para>：新段落

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

///  MyName1 
           
            MyName2
            MyName3

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

网上抄录的

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. <(小于) <
3. >(大于) >
4. "(双引号) "
5. '(单引号) '

需要注意的是

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

/// /// 对象池 ( 支持模板 )/// 
/// 
     
      /// 这是一个对像池, 可以池化所有 TObject 对像 ( 支持模板 )/// 
      /// 用法:/// 
       
        在一个全局的地方定义: 
       /// 
       
        var
       /// 
       
          Pooler: TObjPool<要收集的类名>
       /// /// 
      /// 
       
        用到的地方: 
       /// 
       
        tmpObj := Pooler.LockObj as Txxx;
       /// 
       
        if Assigned(tmpObj) then
       /// 
       
        try
       /// 
       
        finally
       /// 
       
          Pooler.UnlockObj(tmpObj);
       /// 
       
        end;
       /// /// 
      /// 
       
        初始化: 
       /// 
       
        initialization
       /// 
       
          Pooler := TObjPool<要收集的类名>(对象池最大值, 对象池最小值).Create;
       /// 
       
        finallization
       /// 
       
          Pooler.Free;
       /// ///