Ocaml的docstring

寫一個軟體,通常需要有Document String 嵌入程式碼,雖然形式類似註解,但是可以產生比較好閱讀的 reference。

OCaml 的docstring介紹比較少,所以在這裡介紹

模組嵌入docstring

在模組之後各open xxx之後,第一行輸入(** [docstring內容] *),記得註解的頭要兩個星號**,如:

open A
open B
(**
I'm a module
*)

[body of program...]

函數嵌入docstring

在函數前輸入(** [docstring內容] *),如


(**
the function's docstring
intro

*)
let foo x = ...


Docstring 的格式語法

Ocaml的格式語法不同於Markdown,比較特殊,以下是舉隅:

  • {n 內容}:第n級標題,n是整數
  • {b 粗體的文字}:粗體文字
  • 無序列表如下:
{ul {- 第一條內容}
{- 第二條內容}
{- 第三條內容}}
  • []:單行程式碼
  • 多行程式碼如下:
{[
第一行內容
第二行內容
]}

產出html

因主要大家看文件多用html格式,以下簡介產生html網頁的方法:

ocamlfind ocamldoc [-package 引用的套件] -html -charset=utf-8 程式碼 -d docs

ocamldoc 是主要的生成程式,-charset=utf-8 要求編碼是utf-8,-d 指定產出的目錄。


參考資料