headerdoc2html ： header檔案說明文檔

閱讀本文前，請先安裝蘋果的headerdoc

---

headerdoc2html是用來產生header檔案說明文檔用的（.html）
貌似還有一個Doxygen，不過沒用過﹍﹍

使用方法如下：
假設我現在有 main.m Person.m Person.h Student.m Student.h 這幾個文檔，然後Student是Person的Subclass
則於Makefile這樣寫：

doc: main.m Student.m Student.h
 headerdoc2html -o Documentation Person.h
 headerdoc2html -o Documentation Student.h
 gatherheaderdoc Documentation

注意，從第二行開始，開頭的空白一定要是tab字元（），如果是空格會有問題﹍﹍
不過基本上寫Makefile這應該算常識吧﹍﹍

當然，你也可以用偷懶法：doc: *.m *.h
headerdoc2html -o Documentation *.h
gatherheaderdoc Documentation不過我有同學用這個會出現bug，不知道為什麼﹍﹍


順帶一提，Documentation是生產出來的說明檔放置的資料夾。

寫完Makefile後，接下來是修訂自己的header文件了﹍﹍
每個.h文件都必須有註解來告知headerdoc2html這東西幹麼用的

以上面的makefile為例：
如果是Obj C的話：
#import <Foundation/Foundation.h>
#import "Person.h"
/*!
@class Student
@abstract Student Class的abstract
@discussion Student Class的discussion
@superclass Person
*/

@interface Student: Person{

int studentId;
}
/*!
@method studentId
@abstract to get the student Id
@discussion ....
*/
- (int)studentId;
@end
每個class、method、function都要寫一段像下面的註解
/*!
@class ...
@abstract ...
@discussion ...
*/
只要有寫就會編譯出來，雖然abstract或discussion沒寫的話會發生error，但仍舊可以編譯出來html的說明文檔。
至於詳細內容，就請參考api：headerdoc2html API
另外還有原代碼可以參考：

• 8.7.15版
• 7.3.0版
• 7.0版

這時我就要抱怨一下，究竟是哪個天才想到把API這樣寫得啊，一打開網頁就呈現html碼
html碼耶，不是網頁內容耶！
雖然是有[plain text]這按鈕在，但是每開一個連結就要按一次，這是多麼虐人啊﹍﹍
真不知道到底是誰想到的﹍﹍


Apr 27th補充：

1. No header or class discussion/abstract found. Creating dummy file for default content page.

---

這個訊息出現就如同自面上的意思，沒寫class／header的註解
只要在程式碼寫上下面的code即可
/*!
@header ...
@abstract ...
@discussion ...
*/
個人習慣放在#import 和 @class / @interface 之間

2. @class、@method、@function 可以不用寫

---

以下面代碼為例
/*!
@function setNumber
@abstract to set the student number
@discussion
@param newNo new student number
*/
- (void)setNumber: (int) newNo;
｢@function setNumber」這行可以不用寫的
如果寫了的話，生成的documentation會像下面這樣：

setNumber:setNumber

---

to set the student number

- (void)setNumber: (int) newNo;