newlisp 注释生成文档

最近写了一个newlisp_armory库，用来实现一些newlisp自身不支持的操作。比如跨windows和ubuntu的目录拷贝功能等。

自己用的时候，发现没有API reference文档参考，很不方便。于是学习了如何用注释生成文档。

在Ubuntu环境下，首先要下载newlispdoc程序的源码：http://newlisp.org/syntax.cgi?code/newlispdoc.txt

将文件重命名为newlispdoc，添加执行权限，复制到/usr/bin目录下。

也可直接从我的github项目中获得：https://github.com/csfreebird/newlisp_armory.git

然后注意注释的写法，下面是个例子：

;; file.lsp;; @module file;; @description file module provides some file operations on both Ubuntu and Windows;; @location file.lsp;; @version 1.0;; @author Dean Chen;; @example;; (let ((test-dir1 (append (real-path) file:file-seperator "a")) (test-dir2 (append (real-path) file:file-seperator "b")));;   (make-dir test-dir1);;   (make-dir test-dir2);;   (if (directory? test-dir1);;       (begin;; (unless (catch (file:copy-folder test-dir1 test-dir2) 'result);; (println (append "catch error: " result));; (println "test copy-folder failed"));; (file:remove-folder test-dir1);; (file:remove-folder test-dir2))))(context 'file);; @syntax (file:init);; @throw Throw error if environment variable NEWLISP_ARMORY_HOME does not exist or is invalid;; @throw Throw error if OS is not Windows or UBuntu;; @note init function will be called automatically when loading file.lsp module, don't call it manually(define (init)  (unless (env "NEWLISP_ARMORY_HOME")  (throw-error "NEWLISP_ARMORY_HOME does not exist"))  (unless (file? (env "NEWLISP_ARMORY_HOME"))  (throw-error "NEWLISP_ARMORY_HOME points to a non-existing file"))  (unless (directory? (env "NEWLISP_ARMORY_HOME"))  (throw-error "NEWLISP_ARMORY_HOME points to a file instead of directory"))  (set 'file-folder (append (env "NEWLISP_ARMORY_HOME") "/codes/file"))  (if   (= ostype "Linux") (load (append file-folder "/file_ubuntu.lsp"))   (= ostype "Win32") (load (append file-folder "/file_win.lsp"))   (throw-error (append "file tool doesn't support this OS for now, ostype:" ostype))   ))

现在运行命令产生doc:

newlispdoc file.lsp

由于我还有几个支持不同平台的文件，file_ubuntu.lsp和file.win.lsp，似乎newlispdoc没有这么智能。因此我将file_ubuntu.lsp的注释复制到file.lsp中，不复制源代码。

也能够生成。

下面的截图展示了我的doc:

点击链接后，进入详细页面：

说明：

1. @syntax 作用是在index页面中显示函数名称，注意加上模块名，形如：mongo:connect, 参数也不能少

2. @return 作用是表示返回值

3. @param 参数说明

4. @description 添加描述性文字

5. 自定义标签需要首字母大写