BOO入門/文件
BOO入門 > 文件 (上一章: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 檔案或其他格式的文件。