簡介

　　假如您已經開發出相當酷的控件，并且希望所有人都使用它。那么就不能只給人們發送一個Zip文件，然后希望他們能使用它。您必須把控件交付到silver platter 上去。這個過程中的一個重要部分就是說明文檔，本文將討論為控件添加說明文檔需要采取的步驟。

　　說明文檔的重要性不只體現在使終端用戶興奮方面，它還是控件的驗證過程的一個重要方面。驗證意味著一個獨立的機構（例如，ComponentSource.com），按照特定的測試計劃評估控件，以確保該控件在WebLogic Workshop 中良好地運行。

　　起始點

　　作為本文的基礎，讓我們從一個已有的控件開始，該控件不具備所有必需的說明文檔。它是一個發送和接收電子郵件的helper組件。我們隨后將通過添加必需的說明文檔使該控件完整。參閱下載區，獲得到該基本控件的鏈接。假如您已經下載了代碼，就可以通過本文，把技術應用到基本控件上。

　　一旦完成之后，最終的控件將具有：

• API 說明文檔
  
• 一份用戶指南
  
• 控件屬性描述
  
• 一張內容表
  
• 兩個使用該控件的示例應用程序

　　最后，我們將測試控件的說明文檔。

　　注重：擴展也可以提供說明文檔，但是不如控件的說明文檔重要。API和控件屬性說明文檔，還有示例應用程序不會應用到擴展中。您可以使用文中描述的方法為擴展編寫用戶指南和內容表。

　　驗證過程

　　驗證過程針對BEA WebLogic Workshop版本來驗證控件和擴展，證實它們能夠良好地共同運行。

　　驗證不是強制性的。您可以擴展WebLogic Workshop，然后直接把產品分發給用戶。您還可以把創建的產品郵寄給知識庫，甚至是ComponentSource站點。有人選擇不驗證控件和擴展，因為這個過程有點昂貴。但是要使控件和擴展進入BEA’s PRemier Component Gallery站點，就要求進行驗證。

　　Emailer控件

　　現在讓我們轉向基本控件。Emailer控件方便了電子郵件消息的發送和接收。下載區的start.zip提供了該控件。解壓縮該文件并雙擊EmailerApp.work。選擇默認（示例）WebLogic Workshop服務器實例。圖1顯示了我們討論的控件。

圖1. 項目結構

　　本文不包括控件編寫這個主題。假如需要關于該主題的更多信息，請參考文章Advanced Controls Development Primer，或查看在線說明文檔。

　　在這里我們可以看到該控件提供了三個方法和一個回調。在內部它使用timer控件。該控件可以用于發送電子郵件（sendMail()方法）和接收電子郵件（getMail()或調用start()并等待receiveMail()方法回調）。

　　關于源代碼的注釋：

• 當使用回調把事件推進到用戶類時，還要提供輪詢機制，這很重要。這是因為回調不能被web應用程序使用。
  
• 該控件有一整套JavaDoc。假如控件還沒有良好的JavaDoc，那么現在就動手編寫它們。
  
• 該控件拋出的異常應該在ControlException或其子類內部。

　　目錄結構

　　我們從一個包含多個項目的應用程序開始，而最終我們希望能產生一個包含項目的控件、說明文檔和示例的ZIP安裝文件。該ZIP文件有一個我們將要在此進行討論的非凡結構。

　　首先，需要有下面的一組說明文檔，全部是Html格式的：

應用程序文件夾和文件

內容

EmailerApp/Emailer/doc/en
/partners/dev2dev/...