documentation - lua-ドキュメントのメタデータ

Question

luaでドキュメントを生成するためのメタデータの使用に関するNormanRamseyからのコメントを読みました。

libからドキュメントを生成しようとしていますが、可能であればluadocは使用しません。

ドキュメントを生成するためのこの「メタデータ指向」の方法（使用される方法論、例、またはプログラム）について詳しく知りたいです。

他の答えも歓迎しますが、これはおそらくノーマンが他の誰よりもよく答えることができる質問です。

ありがとう！

Answer 1

まあ、私はこれに答えるべきだと思います。コードはプライムタイムの準備ができていませんが、2010年7月15日以降にリリース可能な状態に到達できる可能性があります。また、事前にコピーを共有できてうれしいです。

2つのアイデアがあります：

1. すべてのモジュールには、という名前のテーブルがあります__doc。モジュール内の各名前は、テーブル内のエントリを取得し__docます。次に例を示します。

   __doc.rfc2822_to_localtime_or_nil = [[function(date) returns number or nil
   Converts RFC2822 date to local time (Unix time).
   ]]
   

   最初の行は、関数の「短いドキュメント」です。いつか動的にチェックできるようになることを願っていますが、今のところは単なるドキュメントです。残りは「長いドキュメント」です。さらにいくつかあります：

   __doc.to_string = [[function(T) returns string
   Converts a message to a string in RFC 2822 format.]]
   
   __doc.to_orig_string = [[function(T) returns string
   Returns the string originally used to create the message,
   which may or may comply with RFC 2822.]]
   

   __doc.__overview、、などのさまざまな特殊フィールドもあります__doc.T。

2. __docフィールドをクロールして情報を提供するコマンドラインツールがあります。現在、このコードはあまり一般的ではなく、実装は混乱しています。しかし、ここにいくつかのサンプル出力があります：

   パッケージ全体の概要（私を正直に保つために重要な、文書化されていないアイテムのリストに注意してください）：

   % osbf3 internals
   
   Documented modules:
     boot         
     cache        -- the OSBF-Lua message cache
     cfg          
     classifier   
     command_line 
     commands     
     core         
     filter       
     lists        
     log          
     mime         
     mlearn       
     msg          -- parse MIME message and manipulate headers
     options      
     output       
     roc          
     sfid         
     util         
   
   Undocumented functions:
     core.hash           
     core.utf8tohtml     
     options.env_default 
   

   1つのモジュールの概要：

   : nr@yorkie 5874 ; osbf3 internals -short msg
   
   msg: T = The representation of a message
   
   msg.add_header = function(T, tag, contents)
   
   msg.del_header = function(T, tag, ...)
   
   msg.fingerprint = function(string) returns string
   
   msg.has_sfid = function(msg.T) returns bool
   
   msg.header_indices = function(msg, tag, ...) returns iterator
   
   msg.headers_tagged = function(msg, tag, ...) returns iterator
   
   msg.of_string = function(s, uncertain) returns T or nil
   
   msg.sfid = function(msg.T, [msgspec]) returns string or calls error
   
   msg.synopsis = function(T, w) returns string
   
   msg.to_orig_string = function(T) returns string
   
   msg.to_string = function(T) returns string
   

   1つの機能のドキュメント：

   % osbf3 internals msg.synopsis
   
   msg.synopsis = function(T, w) returns string
   Returns a string of width w (default 60) which is a synopsis of the
   message T.  The synopsis is formed from the Subject: line and the
   first few words of the body.
   

サーバーがダウンしていますが、機会があれば、誰かがこのコードを試してみたい場合は、このコードへのリンクを投稿します。