четверг, 1 декабря 2011 г.

AutoLISP. Автоматическая генерация документации кода

Очень давно мечтал, о вкусности, которая есть во многих языках программирования, но почему-то  нет в AutoLISP, хотя может плохо искал. Я говорю об автоматической генераций документации на файл исходника. В мною любимом Perl есть, в Ruby есть, в Python есть, в C# есть и во многих других...

Например, как это выглядит в C#:

/// <summary>
/// Test method to show
/// automatic documentation syntax
/// </summary>
/// <param name="data">data to
/// show params</param>

Мне это надоело и я решил избрести велосипед. Посидел вечерок, и набросал структуру требуемого комментария и собственно скрипт на Python, который все это дело парсит и превращает в HTML-файл с определенной структурой. Разработанный мной вид комментария следующий:
;;; <LISPDOC>
;;; <SUBR>(autolisp-subroutine arg1 arg2)</SUBR>
;;; <DESC>AutoCAD subroutine description</DESC>
;;; <ARG>arg1 - test argument 1</ARG>
;;; <ARG>arg2 - test argument 2</ARG>
;;; <RET>result string</RET>
;;; </LISPDOC>

Где:
<LISPDOC></LISPDOC> - тело комментария
<SUBR></SUBR> - синтаксис функции
<DESC></DESC> - описание функции
<ARG></ARG> - описание аргумента
<RET></RET> - возвращаемое значение

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

Чуть не забыл, синтаксис следующий:

>python lispdoc.py source.lsp

Выполненная команда создаст файл в каталоге с исходником HTML-файл документации на код. Собственно и все, для документирования по всем файлам внутри каталога я создал cmd-шник c вызовом find -exec. Но так как я использую Linux-версию команды find, то приводить его здесь не буду.

Это незаконченная версия документирования кода, так что если есть предложения, прошу в комментарии

1 комментарий: