lua - метаданные для документации - PullRequest
Новая
       26

lua - метаданные для документации

3 голосов
/ 23 июня 2010

Я прочитал комментарий от Нормана Рэмси о использовании метаданных для создания документации в lua .

Я пытаюсь сгенерировать документацию из моей библиотеки, и я бы не стал использовать luadoc, если это возможно.

Я хотел бы узнать больше об этом "метаданных" методе для создания документации - методологии, примеров или используемых программ.

Другие ответы приветствуются, но на этот вопрос, вероятно, Норман может ответить лучше, чем кто-либо другой.

Спасибо!

1 Ответ

4 голосов
/ 23 июня 2010

Ну, полагаю, я должен ответить на это.Код не готов к работе в прайм-тайм, хотя после 15 июля 2010 г. я смогу перейти в высвобождаемое состояние и с удовольствием поделюсь копиями.

Есть две идеи:

  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

    Краткий обзор одного модуля:

    : 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

    Документация по одной функции: 

    % 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.

Наши серверы не работают, но когда я получу возможность, я опубликую ссылку на этот кодесли кто-то хочет поиграть с ним.

...