Есть ли способ написать «стандартные» комментарии в Makefile, чтобы позже передать их в Doxygen-подобную программу, чтобы вывести хорошую (HTML или man) документацию? Я хотел бы получить четкий обзор моих основных целей, но ничего необычного.Как документировать make-файл?
ответ
Одним из приятных прикосновений является предоставление фальшивой цели help
, которая печатает сводку целей и опций. Из ядра Linux Makefile
:
help:
@echo 'Cleaning targets:'
@echo ' clean - Remove most generated files but keep the config and'
@echo ' enough build support to build external modules'
@echo ' mrproper - Remove all generated files + config + various backup files'
@echo ' distclean - mrproper + remove editor backup and patch files'
@echo ''
@echo 'Configuration targets:'
@$(MAKE) -f $(srctree)/scripts/kconfig/Makefile help
@echo ''
Это может быть немного работы, чтобы поддерживать документацию таким образом, но я нахожу это хорошо отделяет то, что предназначено для «пользователей» против того, что предназначено для людей, поддержания самого Makefile
(встроенные комментарии).
Self-Documenting Makefiles (John Graham-Cumming, 2005) позволяет вам писать помощь вместе с каждым правилом. Это легкое и очень отличное решение, которое работает как минимум с GNU Make.
Вот мой slightly modified version (раздел def-help помогает организовать длинные списки правил).
Я сделал свое собственное решение, используя короткий скрипт на Perl, который отформатирован помощи других инструментов GNU:
SCRIPT_VERSION=v1.0
SCRIPT_AUTHOR=John Doe
all: ##@Build Build all the project
clean: ##@Cleaning Remove all intermediate objects
mrproper: clean ##@Cleaning Remove all output and interemediate objects
HELP_FUN = \
%help; while(<>){[email protected]{$$help{$$2//'options'}},[$$1,$$3] \
if/^([\w-_]+)\s*:.*\#\#(?:@(\w+))?\s(.*)$$/}; \
print"$$_:\n", map" $$_->[0]".(" "x(20-length($$_->[0])))."$$_->[1]\n",\
@{$$help{$$_}},"\n" for keys %help; \
help: ##@Miscellaneous Show this help
@echo -e "Usage: make [target] ...\n"
@perl -e '$(HELP_FUN)' $(MAKEFILE_LIST)
@echo -e "Written by $(SCRIPT_AUTHOR), version $(SCRIPT_VERSION)"
@echo -e "Please report any bug or error to the author."
Что дает это:
$ make help
Usage: make [target] ...
Miscellaneous:
help Show this help
Build:
all Build all the project
Cleaning:
clean Remove all intermediate objects
mrproper Remove all output and interemediate objects
Written by John Doe, version v1.0
Please report any bug or error to the author.
Небольшое улучшение бит HELP_FUN: замените 'if/^ (\ w +) \ s *:' с 'if/^ ([\ w -_] +) \ s *:', чтобы разрешить целевые объекты типа «this-target» или «that_target». – th3n3rd
Ниже более простое решение, которое не требуют определения пользовательских функций или агрегирования текста справки вдали от правил, которые они документируют.
# This is a regular comment, that will not be displayed
## ----------------------------------------------------------------------
## This is a help comment. The purpose of this Makefile is to demonstrate
## a simple help mechanism that uses comments defined alongside the rules
## they describe without the need of additional help files or echoing of
## descriptions. Help comments are displayed in the order defined within
## the Makefile.
## ----------------------------------------------------------------------
help: ## Show this help.
@sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST)
build: ## Build something.
install: ## Install something.
deploy: ## Deploy something.
format: ## Help comments are display with their leading whitespace. For
## example, all comments in this snippet are aligned with spaces.
Запуск make
или make help
результатов в следующем:
----------------------------------------------------------------------
This is a help comment. The purpose of this Makefile is to demonstrate
a simple help mechanism that uses comments defined alongside the rules
they describe without the need of additional help files or echoing of
descriptions. Help comments are displayed in the order defined within
the Makefile.
----------------------------------------------------------------------
help: Show this help.
build: Build something.
install: Install something.
deploy: Deploy something.
format: Help comments are display with their leading whitespace. For
example, all comments in this snippet are aligned with spaces.
- 1. Как документировать основной метод?
- 2. Как документировать документальные тесты?
- 3. Как документировать пакет python
- 4. Как документировать RESTful API?
- 5. как документировать флягу webapp
- 6. Как документировать процедурное программирование?
- 7. Как документировать Закрытие
- 8. Как документировать проект Python?
- 9. Как документировать код vbscript
- 10. Как документировать базу данных
- 11. Как документировать XML-схему?
- 12. Как документировать функцию оболочки?
- 13. Как документировать унаследованные элементы?
- 14. Как документировать дополнительные параметры
- 15. Как документировать договор объекта
- 16. Как документировать программные алгоритмы?
- 17. Как документировать C# dll
- 18. Как документировать переменную Python?
- 19. Как документировать исключения?
- 20. Как документировать файлы .properties?
- 21. Как документировать через графику
- 22. Как документировать свойство класса
- 23. Как документировать массив из [type]?
- 24. Как документировать параметр «объект» метода
- 25. RAML как документировать вложенные параметры
- 26. Как документировать аргумент BackgroundWorker.RunWorkerAsync (Object)?
- 27. Как документировать изменения сторонних библиотек?
- 28. Как документировать неудачные тесты JUnit
- 29. Как документировать исключения методов async?
- 30. Как правильно документировать регулярное выражение?
Может быть, я не достаточно терпелив, но я сомневаюсь, что есть что-нибудь еще, кроме того, что вы упоминались. Большое спасибо !! –
Если вы хотите, чтобы какой-то автоматизированный материал взглянул на [make-help] (https://github.com/gibatronic/make-help). – gibatronic