Support OpenKore:
OpenKore 有一個工具，叫做 createdoc.pl，可用來把字裡行間的註解轉為 HTML 文件。這有點類似其它的文件說明工具像是 Doxygen 與 Javadoc。OpenKore 原始碼說明文件 就全都是用這個工具來產生的。
Contents |
文件以兩個 # 做開頭，後面跟著註解行（註解行行首只要一個 # 與一個空格）。 這兒是一個文件開頭的範例：
## # distance(r_hash1, r_hash2) # pos1, pos2: references to position hash tables. # Returns: the distance as a floating point number. # # Calculates the pythagorean distance between pos1 and pos2. # # FIXME: Some things in RO should use block distance instead. # Discussion at # http://openkore.sourceforge.net/forum/viewtopic.php?t=9176 # # Example: # # Calculates the distance between you and a monster # my $dist = distance($char->{pos_to}, # $monsters{$ID}{pos_to});
顯示的結果可由 這裡 觀看。
說明以一個功能或方法的宣告做開頭。後面緊跟著參數（假如有的話）的描述、回傳值的描述與先決條件和後決條件。然後接著一個空行，空行之後是詳細的描述。最後，你可以寫一個範例。
你不用詳細指明所有東西。你可以捨棄一些東西，像這樣也是可被接受的：
## # boolean $Actor->snipable() # # Returns whether or not you have snipable LOS to the actor.
顯示的結果可由 這裡 觀看。
關於 Perl 比較頭痛的一點是所有東西的類型都是變動的，因此變數的類型要視前後內容而定。我們的文件工具支援對功能、方法、變數與雜湊領域做類型的定義。我們使用 Java-like 的宣告。
void - 只用在回傳值這種類型。
int - 無限制的整數。
float - 一個無限制的浮點實數。我們不使用 double：反正 Perl 對此不要緊。
boolean - 一個非零的數（若為真），或零、undef（若為假）。
Object - 一個 Perl 類別物件。（例如所有 blessed 的純量）
String - 一個文字字串，通常包含有人類看得懂的資料。 *
Bytes - a string containing arbitrary binary data. *
UtfBytes - 一個含有有效 UTF-8 資料的字串。所有的 UtfBytes 變數們都自動地是 Bytes 的類型，但反之則不一定。
Scalar - 一個 Perl 的純量。換句話說，是類型未定義的 "某些變數"。
Hash - 一個 Perl 的雜湊。
Array - 一個 Perl 的陣列。
* 重要：請參見 OpenKore internationalization support 以獲得有關 String, Bytes 與 UtfBytes 類型的資訊。
我們使用 '*' 來指出某些東西是一個 參考，所以
void foo(Array *bar)
表示 foo() 被認為是指向一個陣列的參考。
你不應該對於 陣列/雜湊 定義域寫上 '*'！陣列與雜湊只能包含對於其它 陣列/雜湊 的參考，而非它們本身就是實際的其它 陣列/雜湊。因此為它們寫上 '*' 是多餘的。所以請這樣寫
Array $hash{something}
而不是寫成這樣
Array* $hash{something}
你可以用 Java generics 或 C++ templates style 來對 陣列/雜湊 的元素定義其類型。語法：
Array<ElementDataType> Hash<ElementDataType>
舉例來說，
Array<String> $foo->{bar}
表示每個在 $foo->{bar} 裡的元素是一個 String。
Array<String *> $foo->{bar}
表示每個在 $foo->{bar} 裡的元素是對一個 String 的一個參考。
Array<int>* myFunction()
表示 myFunction 回傳對一個陣列的一個參考，該陣列的每一個元素都是一個整數。
## # void $BaseWebServerProcess->status(int statusCode, String statusMsg) # statusCode: a HTTP status code. # statusMsg: the associated HTTP status message. # Requires: # defined($statusMsg) <br> # $process->print() or $process->shortResponse() must not have been called before. # # Schedule a HTTP response status message for sending. See the # HTTP specification (section 10) for a list of codes. This status code will be sent when the connection to # the web browser is closed, or when you first call $process->print() or $process->shortResponse(). # If you have sent a HTTP status before, the previous status is overwritten by this one. # # See also: $process->header() # # Example: # $process->status(404, "File Not Found");
輸出的結果可在 這裡 觀看。
你也可以使用 abstract 關鍵字來對類別定義抽象的方法。
## # abstract void $BaseServer->onClientData(Base::Server::Client client, Bytes data, int index) # client: a client object (see overview). # data: the data this client received. # index: the client's index (same as $client->getIndex). # Requires: defined($client) && defined($data) # # This method is called when a client has received data.
輸出的結果可在 這裡 觀看。