BOO入門/文件

一份可溝通的東西，用來解釋物件、系統或程序的某些特性。

我會把最重要的部份保留在最後：一份加上文件，說明自身代碼的代碼。

當文件化你的代碼時，要確實記住：

你的文件應該要以英文書寫。
使用完整的句子。
避免拼字/文法錯誤。
時態使用現在式。

文件書寫時，以三個雙引號包起來。

// 為函數加上摘要文件
def Hello():
"""Says "hello" to the world."""
    print "Hello, World!"

Hello()

至少，你應該要加上一段簡單摘要的文件字串(docstring)。如果你的文件字串超過一行，那麼三個雙引號應該獨立為一行。你或許注意到了，'Says "hello" to the world.' 不是一個完整的句子。摘要裡的第一個句子，其實有"This member"的意思。(譯註：所以實際上是 'This member says "hello" to the world.')

引數也可以加以文件化。

// 引數
def Hello(name as string):
"""
Say "hello" to the given name.
Param name: The name to say hello to.
"""
    print "Hello, ${name}!"

Hello()

試著自己讀讀看：'Say "hello" to this given name. Parameter name is defined as the name to say hello to.' (對給定的名字說 'hello'。引數 name 會作為要說 hello 的對象。') 這應該能影響你，讓你繼續使用完整的句子來文件化你的代碼。

如果對引數的描述超過一行，你應該將描述移到新的一行，並且加上縮排。

// 長引數
def Hello(name as string):
"""
Say "hello" to the given name.
Param name:
    The name to say hello to.
    It might do other things as well.
"""
    print "Hello, ${name}!"

這同樣適用於任何區塊。這裡有一份適用的標籤(Tag)列表(譯註：Param 就是其中的一個 tag)：

Tag	描述
No tag	成員的摘要。
Param <name>: <description>	用來描述方法所使用的引數 <name>
Returns: <description>	描述方法的回傳值。
Remarks: <text>	對成員提供更具描述性的文字。
Raises <exception>: <description>	描述為甚麼會提出例外。
Example: <short_description>: <code_block>	提供範例。
Include <filename>: <tagpath>[@<name>="<id>"]	表示需要引用其他檔案。
Permission <permission>: <description>	描述所需要的許可(Permission)。
See Also: <reference>	指定你想出現在 See Also 節裡的參考。

然後這兒是一份可以在 tag 內使用的 tag 列表：

Tag	描述
* <item><nowiki> \| 無編號的列表 \|- \| <nowiki># <item>	有數字的列表
<<reference>>	對參考提供連結，例如：<int> 或 <string> 表示連結到整數與字串的說明。
[<param_reference>]	參考方法的某個參數。

這兒，是一份比較完整，加上文件的代碼：

// 文件範例
import System

class MyClass:
"""Performs specific duties."""
    def constructor():
    """Initializes an instance of <MyClass>"""
        _rand = Random()
    
    def Commit():
    """Commits an action."""
        pass
    
    def CalculateDouble(i as int) as int:
    """
    Returns double the value of [i].
    Parameter i: An <int> to be doubled.
    Returns: Double the value of [i].
    """
        return i * 2
    
    def CauseError():
    """
    Causes an error.
    Remarks: This method has not been implemented.
    Raises NotImplementedException: This has not been implemented yet.
    """
        return NotImplementedException("CauseError() is not implemented")
    
    def DoSomething() as int:
    """
    Returns a number.
    Example: Here is a short example:
        print DoSomething()
    Returns: An <int>.
    See Also: MakeChaos()
    """
        return 0
    
    def MakeChaos():
    """
    Creates Chaos.
    Include file.xml: Foo/Bar[@id="entropy"]
    Permission Security.PermissionSet: Everyone can access this method.
    """
        print "I am making chaos: ${_rand.Next(100)}"
    
    def Execute():
    """
    Executes the protocol.
    Does one of two things,
    # Gets a sunbath.
    # Doesn't get a sunbath.
    """
        if _rand.Next(2) == 0:
            print "I sunbathe."
        else:
            print "I decide not to sunbathe."
    
    def Calculate():
    """
    Does these things, in no particular order,
    * Says "Hello"
    * Looks at you
    * Says "Goodbye"
    """
        thingsToDo = ["I look at you.", 'I say "Hello."', 'I say "Goodbye."']
        while thingsToDo.Length > 0:
            num = _rand.Next(thingsToDo.Length)
            print thingsToDo[num]
            thingsToDo.RemoveAt(num)
    
    [Property(Name)]
    _name as string
    """A name""" // documents the property, not the field
    
    Age as int:
    """An age"""
        get:
            return _rand.Next(8) + 18
    
    _age as int
    
    _rand as Random

這應該能讓你比較知道如何去為你的代碼加上文件。

我記得 Dick Brandon 說過一句很好的話：

 引述自: Dick Brandon
 文件就像性：如果它好的話，那當然很好﹔如果它爛的話，還是比什麼都沒有好。

譯註：這裡還是沒提到，當一份代碼有了文件說明自身以後，會在什麼地方用到。加上文件說明，在編譯以後，會產生一份 xml 檔案，接著，你可以使用 NDoc 或是 Sandcastle 來產生出 Help 檔案或其他格式的文件。