«
»

Commentor – генератор ASDoc комментариев

Upd. 14.01.2009
Исправил ошибку с некорректной работой -add-see функции. Добавил номер версии в справку. Скачать пакет Commentor v. 0.9.5.

Данная программа позволит быстро заполнить ваши *.as файлы с классами шаблонными комментариями. В отличие от других велосипедов, эта программа появилась именно тогда, когда она мне понадобилась. А необходимость в ней возникает обычно, перед сдачей проекта или при передаче другому разработчику. Лично меня раздражают такие объёмные комментарии в коде, над которым я работаю – надоедает постоянно прокручивать несколько страниц в происках какого-то кусочка кода(есть, конечно же, удобные навигаторы в удобных IDE, но всё равно – мне удобнее без ASDoc комментариев). Поэтому вопрос о комментировании кода встаёт остро и за день, если повезёт, до передачи проекта или кода.

В первый раз я её реализовал в виде PHP скрипта, запускаемого на локальном web сервере. Суть его была в том, что он вставлял шаблонный комментарий во все *.as файлы, находящиеся в одной с ним и во вложенных папках. Потом, я о нём благополучно забыл, а недавно опять он понадобился, но кроме самой первой версии я найти больше ничего не смог. Не долго поискал(совсем чуть-чуть) что-то подобное и решил переписать и дополнить существующий скрипт. Теперь он распространяется в виде исполняемого EXE файла и исходного PHP файла, если понадобится запустить на отличной от Windows системе.

Программа не имеет оконного интерфейса, но её использование не должно доставлять трудностей – я попытался максимально облегчить передачу параметров в программу.

Пример работы

Исходный файл(это не образцовый класс и даже не рабочий, его прародитель использовался для тестирования):

  1. package aw.test{
  2. 	public dynamic final class Test	extends Sprite{
  3. 		namespace some_ns = 'some_ns';
  4. 		static private const NOT_XML_DATA1 = (a<b && 4>10);
  5. 		static private const XML_DATA1:XML = <![CDATA[<some_xml/><avg/>>>({[]]>;
  6. 		static private const XML_DATA2:XML = <some_xml arg="true" mx:level="45">
  7. 			<child>
  8. 				<![CDATA[<some_xml/><avg/>>>({[]]>
  9. 			</child>
  10. 		</some_xml>;
  11. 		static public const REGEXP:RegExp = /\}\]\/		public function someFunc\(\):void\{\}/;
  12. 		function Commentor():void{
  13. 			super();
  14. 		}
  15. 		internal function test(arg1:Object/*COMMENT*/, ...args:Array):void/*COMMENT*/{
  16. 			var value;
  17. 			var str:String = " public function someFunc(){}";
  18. 			/*
  19. 			This is public function
  20. 			*/
  21. 		}
  22. 		public function get getProp():String{
  23. 			return '';
  24. 		}
  25. 		override some_ns function get getProp():int{
  26. 			return '';
  27. 		}
  28. 		static protected var _document:aw.external.jsinterface.objects.JSDocument;
  29. 		static public function get document():aw.external.jsinterface.objects.JSDocument{
  30. 			if(!_document){
  31. 				_document = JSCore.getDocument();
  32. 			}
  33. 			return _document;
  34. 		}
  35. 	}
  36. }

Строка запуска: commentor -author "Galaburda a_[w] Oleg http://actualwave.com/" -space-rows 1 -info "This is test file for commentor row 1" -info "This is test file for commentor row 2" -input Test.as -output asdoc\
Полученный результат:

  1. package aw.test{
  2.  
  3. 	/**
  4. 	*
  5. 	* This is test file for commentor row 1
  6. 	* This is test file for commentor row 2
  7. 	* @public
  8. 	* @author Galaburda a_[w] Oleg http://actualwave.com/
  9. 	*/
  10. 	public dynamic final class Test	extends Sprite{
  11.  
  12. 		/**
  13. 		*
  14. 		* @public (namespace)
  15. 		*/
  16. 		namespace some_ns = 'some_ns';
  17.  
  18. 		/**
  19. 		*
  20. 		* @private (constant)
  21. 		*/
  22. 		static private const NOT_XML_DATA1 = (a<b && 4>10);
  23.  
  24. 		/**
  25. 		*
  26. 		* @private (constant)
  27. 		*/
  28. 		static private const XML_DATA1:XML = <![CDATA[<some_xml/><avg/>>>({[]]>;
  29.  
  30. 		/**
  31. 		*
  32. 		* @private (constant)
  33. 		*/
  34. 		static private const XML_DATA2:XML = <some_xml arg="true" mx:level="45">
  35. 			<child>
  36. 				<![CDATA[<some_xml/><avg/>>>({[]]>
  37. 			</child>
  38. 		</some_xml>;
  39.  
  40. 		/**
  41. 		*
  42. 		* @public (constant)
  43. 		*/
  44. 		static public const REGEXP:RegExp = /\}\]\/		public function someFunc\(\):void\{\}/;
  45.  
  46. 		/**
  47. 		*
  48. 		* @public
  49. 		* @return void
  50. 		*/
  51. 		function Commentor():void{
  52. 			super();
  53. 		}
  54.  
  55. 		/**
  56. 		*
  57. 		* @private (internal)
  58. 		* @param arg1
  59. 		* @param args
  60. 		* @return void
  61. 		*/
  62. 		internal function test(arg1:Object/*COMMENT*/, ...args:Array):void/*COMMENT*/{
  63. 			var value;
  64. 			var str:String = " public function someFunc(){}";
  65. 			/*
  66. 			This is public function
  67. 			*/
  68. 		}
  69.  
  70. 		/**
  71. 		*
  72. 		* @public (getter)
  73. 		* @return String
  74. 		*/
  75. 		public function get getProp():String{
  76. 			return '';
  77. 		}
  78.  
  79. 		/**
  80. 		*
  81. 		* @public (some_ns,getter)
  82. 		* @return int
  83. 		*/
  84. 		override some_ns function get getProp():int{
  85. 			return '';
  86. 		}
  87.  
  88. 		/**
  89. 		*
  90. 		* @private (protected)
  91. 		*/
  92. 		static protected var _document:aw.external.jsinterface.objects.JSDocument;
  93.  
  94. 		/**
  95. 		*
  96. 		* @public (getter)
  97. 		* @return aw.external.jsinterface.objects.JSDocument
  98. 		*/
  99. 		static public function get document():aw.external.jsinterface.objects.JSDocument{
  100. 			if(!_document){
  101. 				_document = JSCore.getDocument();
  102. 			}
  103. 			return _document;
  104. 		}
  105. 	}
  106. }

Синтаксис

Передача параметров, в общем, происходит так:

commentor –param value

Между параметром и значением стоит пробел, он же стоит и между параметрами:

commentor –param1 value1 –param2 value2 –param3 value3

Параметры бывают нескольких типов и записываются они так:

 
Int commentor –param1 123
String (в одно слово) commentor –param1 string
String (в одно и более слов) commentor –param1 "string string string"
 
Если вы указываете путь к файлу, то должны пользоваться правилами передачи строк.
 
Boolean commentor –param1 true
 
Булев тип может быть представлен как традиционной записью true/false так и цыфровой – 1/0.
 
Array commentor –param1 value1 value2 value3 value4
 
Значения массива идут через пробел. Вот здесь я остановлюсь по подробнее, т.к. PHP, перед подачей полученных параметров, обрабатывает и удаляет кавычки из получаемых параметров и если была передана строка с предваряющим знаком тире, то точно нельзя сказать, была ли это новая команда или её значение. Все команды предваряются знаком тире и чередуются со значениями – «команда значение команда значение команда значение…", но если следующая команда не предваряется знаком тире, то она автоматически считается значением и передаётся как значение последней переданной команды. Так, что не вызовут ошибки такие команды:
 
Boolean commentor –param1 true false true false
Int commentor –param1 123 456 789
 
Значением команды будет считаться последнее полученное. Но повторять параметры, которые не являются массивами нельзя - это вызовет ошибку. А с массивами(чисто теоретически) может возникнуть такая ситуация:
 
commentor –param1 "-my first string" "-my second string"
 
Как вы, наверно, уже догадались – эта запись вызовет ошибку. Поэтому я не стал ограничивать параметры в количестве и решил позволить такую запись:
 
commentor –param1 "-my first string" –param1 "-my second string"
 
Поскольку программа точно знает, что следующая строка после параметра может быть только значением и ничем иным, то она передаётся без проверки. Повторение параметров позволительно и не для массивов – каждое следующее значение перезаписывает предыдущее.

Параметров без значений быть не может(за исключением команды -help).

Параметры

-help

Единственный параметр, который можно передавать без значения. Как только программа получает его, то сразу выводит помощь и прекращает работу. Такого же результата можно добиться, если не передавать параметров вовсе.

-input тип String, значение по умолчанию отсутствует.

Этот параметр является единственным обязательным и указывает путь, где брать исходные файлы. Путь может указывать на папку или файл.

-output тип String, значение по умолчанию отсутствует.

Указывает на папку или файл для записи результатов выполнения. Если не указан, то берётся значение параметра "-input" и автоматически параметр "-overwrite" получает значение "true". Если в параметре "-input" указан файл, а в "-output" – папка, то в этой папке будет создан файл с именем "-input" и в него будет произведена запись.

-overwrite тип Boolean, значение по умолчанию "false".

Позволяет перезаписывать существующие файлы.

-recursive тип Boolean, значение по умолчанию "true".

Указывает на необходимость обработки вложенных папок. Если задано значение "false", то будут обработаны только вложенные файлы, а вложенные папки будут пропущены.

-space-rows тип Int, значение по умолчанию "1".

Количество пустых строк перед комментарием.

-empty-rows тип Int, значение по умолчанию "1".

Количество пустых строк в комментариях.

-show-public тип Boolean, значение по умолчанию "true".

Добавляет ключевое слово @public ко всем публичным членам класса. Если установлено в "true", а "-hide-nonpublic" - в "false", то все члены класса будут отмечены, как @public.

-explain-public тип Boolean, значение по умолчанию "true".

Указывает, нужно ли "объяснять" в скобках члены класса, отмеченные как публичные.
Примеры:
@public (getter)
@public (public_ns, setter)

-hide-nonpublic тип Boolean, значение по умолчанию "true".

Указывает на необходимость спрятать, с помощью ключевого слова @private, все не публичные члены класса.

-private-ns тип Array, значение по умолчанию отсутствует.

Пространства имён комментируемые, как приватные. Если член класса находится в одном из перечисленных пространств имён, то он будет отмечен, как @private.

-explain-private тип Boolean, значение по умолчанию "true".

Указывает, нужно ли "объяснять" в скобках члены класса, отмеченные как приватные.
Примеры:
@private (protected)
@private (internal, constant)

-author тип String, значение по умолчанию отсутствует.

Автор, добавляется только к комментарию класса, если задан. Комментарий класса – комментарий, описывающий конкретный класс и находящийся непосредственно перед объявлением класса.

-info тип Array, значение по умолчанию отсутствует.

Любая информация. Будет помещена в комментарий класса, перед всеми ключевыми словами. Комментарий класса – комментарий, описывающий конкретный класс и находящийся непосредственно перед объявлением класса.

-load-info тип String, значение по умолчанию отсутствует.

Путь к файлу, из которого нужно загружать информацию для комментария класса. Информация из файла загружается сразу в массив строк, по
этому разрешено этот параметр использовать больше одного раза. Комментарий класса – комментарий, описывающий конкретный класс и находящийся непосредственно перед объявлением класса.

-langversion тип Array, значение по умолчанию отсутствует.

Версии языка, к которым применим данный код. Использует ключевое слово @langversion. Добавляется в комментарий к каждому члену класса.

-playerversion тип Array, значение по умолчанию отсутствует.

Версия проигрывателя, для которой предназначен данный код. Использует ключевое слово @playerversion. Добавляется в комментарий к каждому члену класса.

-productversion тип Array, значение по умолчанию отсутствует.

Версия оболочки, в которой будет выполнятся SWF программа. Использует ключевое слово @productversion. Добавляется в комментарий к каждому члену класса.

-add-keyword тип Boolean, значение по умолчанию "false".

Указывает необходимость использования ключевого слова @keyword в комментариях к членам класса.

-use-keyword-ns тип Boolean, значение по умолчанию "false".

Указывает на необходимость указания пространства имён для ключевого слова @keyword. Я вообще, не знаю, на сколько это нужно – добавил «на всякий случай".

-add-see тип Boolean, значение по умолчанию "false".

Добавляет ключевое слово @see для параметров класса и аргументов/возвращаемого типа методов. Для этого параметра необходимо указывать пути к корневым пакетам всех библиотек классов (через параметр "-add-see-path"), типы, находящиеся в которых вы хотели бы отображать. Но, если параметр "-add-see" будет передан со значением "true" и без указания, хотя бы одного пути, что будет использован путь, указанный в параметре "-input".

-add-see-path тип Array, значение по умолчанию отсутствует.

Путь, где находятся классы, на которые можно ссылаться через ключевое слово @see. Если -add-see установлен в true и ничего не передано в -add-see-path, то путь, указанный в -input будет добавлен, как путь по умолчанию. Необходимо указывать только пути на корневые пакеты:
-add-see-path c:\classes\as3\ - не правильно
-add-see-path c:\classes\as3\com\ - правильно
-add-see-path c:\classes\as3\com\utils\ - не правильно
Потому, что путь используется для распознавания пакета, а имя файла - как имя класса (без обработки самого файла).

ActionScript

Данная программа не может гарантировать вам обработку всех инструкций, классов и их членов, описанных в вашем коде. Как и её создатель, данная программа, не любит не форматированный (не правильно оформленный, «грязный" код) код и вполне возможно, что она либо не сможет его прочитать, либо прочитает, но не верно. Поэтому, пожалуйста, соблюдайте элементарные правила оформления кода. Если ваш код оформлен, по вашему мнению, правильно, но вы обнаружили явную ошибку, то буду признателен за багрепорт в комментарии или любым другим, доступным мне, способом.

Загрузить

Пожалуйста, будьте осторожны:
Как и любой другой софт (а особенно эта программа), в этой программе могут быть логические ошибки, приводящие к необратимым последствиям. Это, конечно, не означает, что я не пытался их искоренить – все известные багги были искоренены. Но я считаю обязательной процедуру сохранения резервной копии исходных файлов, перед использованием данной программы.

Пожалуйста, не забывайте, что символ ">" обозначает перенаправление потока вывода!

Скачать пакет Commentor v. 0.9.5.
Проверить на вирусы исполняемый файл можно на сайте Лаборатории Касперского.
В сборке использовался Bambalam PHP EXE Compiler/Embedder

Список файлов содержащихся в архиве Commentor.v095.zip:
asdoc – папка с обработанным файлом Test.as
commentor.exe – файл программы. Только этот файл необходим для выполнения программы и всех его команд.
commentor.php – файл с исходным кодом программы.
example1.bat, example2.bat, example3.bat – примеры командной строки
help_en.txt, help_ru.txt – справка по программе
Test.as – тестовый файл, вызываемый через файл example1.bat

Справка по ASDoc:
Flash-разработка: Теги ASDoc. AS3
Using ASDoc -- Flex 2.01

Метки: , , ,

Эта запись опубликована в Среда, 3/12/2008 , 1:52 дп и размещена в рубрике ActionScript 3, Flash, Поделки. Вы можете следить за обсуждением этой записи с помощью ленты RSS 2.0. Вы можете оставить отзыв, или обратную ссылку с вашего сайта.

Оставить ответ

Вы должны авторизоваться для отправки комментария.