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

  • 需要注意的是

    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>

©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页