newlisp 注释生成文档

最新推荐文章于 2020-10-10 19:57:18 发布

最新推荐文章于 2020-10-10 19:57:18 发布 · 156 阅读

文章标签：

#git #操作系统

本文介绍了一个名为newlisp_armory的库，该库为Newlisp提供了额外的功能，并重点介绍了如何通过适当的注释来生成API文档。作者分享了在Ubuntu环境下安装newlispdoc工具的过程，并给出了具体的注释示例。

部署运行你感兴趣的模型镜像

最近写了一个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: