3 files changed, 114 insertions, 1 deletions

diff --git a/docs/proto/Makefile b/docs/proto/Makefile
new file mode 100644
index 00000000..63086b38
--- /dev/null
+++ b/docs/proto/Makefile
@@ -0,0 +1,18 @@
+
+#.SUFFIXES: .c .txt
+
+# XXX 這有沒有比較好的作法?
+# 直接用 .c.txt 好像會先去看目前目錄有沒有 xxx.c @_@
+
+NAME!=	cd ../../mbbsd/ && ls *.c | sed -e "s/\.c//"
+SRC!=	cd ../../mbbsd/ && ls *.c | sed -e "s/\.c/.txt/"
+
+all: $(SRC)
+
+.for fn in $(NAME)
+$(fn).txt: ../../mbbsd/$(fn).c
+	./cdoc ../../mbbsd/$(fn).c > $(fn).txt
+.endfor
+
+clean:
+	rm -f *.txt
diff --git a/docs/proto/cdoc b/docs/proto/cdoc
new file mode 100755
index 00000000..e9403589
--- /dev/null
+++ b/docs/proto/cdoc
@@ -0,0 +1,75 @@
+#!/usr/bin/perl
+
+# follow javadoc
+# @see http://java.sun.com/j2se/javadoc/writingdoccomments/
+
+use strict;
+
+=cut
+
+�o�ӵ{���i�H�q C ���{���X���A�C�X�Ҧ� statis/non-static �� functions�C
+�C�� function �e���i�H�� javadoc-style �����ѡC�d�Ҧp�U�G
+
+/**
+ * Function of the function func.
+ * @param x variable, if there are more than one @-style description, it
+ *        will end with the next @-style description.
+ * @return void
+ */
+void func(int x)
+{
+    ...
+}
+=cut
+
+my $content;
+
+foreach my $f (@ARGV) {
+    makedoc($f);
+}
+
+
+sub grep_desc
+{
+    my $name = '\w+';
+    my $type = '\w+\s*\*?';
+    my $sentence = '.*';
+
+    my $one_desc = "$name\\s+$sentence";
+    my $desc_head = "\\/\\*\\*\n";
+    my $desc_tail = "\\s*\\*\\/\n";
+    my $desc_line = "\\s*\\*.*\n";
+    my $paramdesc = "\@param\\s+$one_desc(?:\n$desc_line)*";
+    my $returndesc = "\@return\\s+$sentence(?:\n$desc_line)*";
+    my $seedesc = "\@see\\s+$sentence(?:\n$desc_line)*";
+    my $desc = "$desc_head(?:$desc_line)*$desc_tail";
+
+    my $modifier = '(?:static|inline)\\s+';
+    my $one_param = "$type\\s*$name";
+    my $more_param = ",\\s*$one_param";
+    my $param = "(?:$one_param(?:$more_param)*)?";
+    my $func_proto = "(?:$modifier)?$type\\s+$name\\($param\\)";
+
+    $content =~ s/($desc_head(?:$desc_line)*$desc_tail)?($func_proto)\s*{//mo
+	or return undef;
+    my $comment = $1;
+    my $function = $2;
+    $function =~ s/\n/ /g;
+    $function =~ s/\s+/ /g;
+
+    # check comment style here
+
+    return "$function;\n".($comment ? $comment : "/* no comment */\n");
+}
+
+sub makedoc
+{
+    $_ = shift @_;
+    open SRC, "<$_";
+    $content = join "",<SRC>;
+    close SRC;
+    print "/* vim:ft=c */\n\n";
+    while ($_ = grep_desc()) {
+	print "$_\n";
+    }
+}
diff --git a/mbbsd/read.c b/mbbsd/read.c
index 3e665913..1927d929 100644
--- a/mbbsd/read.c
+++ b/mbbsd/read.c
@@ -9,6 +9,11 @@ static int      last_line; // PTT: last_line ��Хi�����̫�@��
 /* ----------------------------------------------------- */
 /* Tag List ����                                         */
 /* ----------------------------------------------------- */
+
+/**
+ * @param locus
+ * @return void
+ */
 void
 UnTagger(int locus)
 {
@@ -262,7 +267,22 @@ cursor_pos(keeploc_t * locmem, int val, int from_top, int isshow)
     return isshow ? PARTUPDATE : HEADERS_RELOAD;
 }
 
-/* �ھ� stypen ��ܤW/�U�@�g�峹 */
+/**
+ * �ھ� stypen ��ܤW/�U�@�g�峹
+ *
+ * @param locmem  �ΨӦs�b�Y�ݪO��Ц�m�� structure�C
+ * @param stypen  ��в��ʪ���k
+ *           CURSOR_FIRST, CURSOR_NEXT, CURSOR_PREV:
+ *             �P��Хثe��m���峹�P���D �� �Ĥ@�g/�U�@�g/�e�@�g �峹�C
+ *           RELATE_FIRST, RELATE_NEXT, RELATE_PREV:
+ *             �P�ثe���\Ū���峹�P���D �� �Ĥ@�g/�U�@�g/�e�@�g �峹�C
+ *           NEWPOST_NEXT, NEWPOST_PREV:
+ *             �U�@��/�e�@�� thread ���Ĥ@�g�C
+ *           AUTHOR_NEXT, AUTHOR_PREV:
+ *             XXX �o�\��ثe�n���S�Ψ�?
+ *
+ * @return �s�����m
+ */
 static int
 thread(keeploc_t * locmem, int stypen)
 {