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>

 

---