Delphi新注释

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

 


 

  • 个人常用
    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. <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>

Delphi新注释

上一篇:WPF 控件功能重写(Combobox回车搜索)


下一篇:WPF 给Button按钮加小图标图片Image