JavaDoc类似于shell脚本的框架？

Question

是否有一个开源或公共域框架可以记录类似于JavaDoc生成的shell脚本？我不需要将其限制为特定的shell脚本，理想情况下我希望在网页上记录API或命令行类型命令的通用框架易于扩展，甚至更好的是自我记录。

Answer 1

如果你有Perl，here就是使用Perl的POD系统来记录shell脚本的人的一个例子。

  

诀窍是将Perl POD部分放在bash“Here-Document”中，紧跟在null命令（no-op）:之后。

     

  
• 从: <<=cut
开始   
• 编写POD格式的手册页
  
• 就是这样。您的POD以=cut结尾，也被定义为shell的结尾Here-doc
  

     

然后可以使用所有常用的Perl工具（如perldoc或perl2html）处理您的脚本，甚至可以使用pod2man生成真正的手册页。

     

例如，这是podtest.sh脚本：

#!/bin/dash

echo This is a plain shell script
echo Followed by POD documentation

: <<=cut
=pod
=head1 NAME

   podtest.sh - Example shell script with embedded POD documentation

     

...

No rights Reserved

=cut

     

将此podtest.sh添加到您的手册页：

 pod2man podtest.sh >/usr/local/share/man/man1/podtest.sh.1

Answer 2

虽然Doxygen不支持bash脚本文件，但可以 make Doxygen work with bash

如果您不介意将文档与代码分开，那么您一定要查看ronn。

您可能还会发现Shocco很有用，即使它与JavaDoc不同（代码是文档的组成部分）。

Answer 3

您可以考虑Doxygen。虽然它主要用于记录像JavaDoc这样的C-ish语言，但你可能会想出一个适用于shell脚本的设置，但有一些争论。

Answer 4

记录的shell脚本的标准方法是使用troff和类似于C的脚本注释。虽然我建议使用Steve的帖子中的“Here-Document”方法，如果你真的需要一些更易于嵌入的东西来嵌入你的troff / pod / rdoc / jdoc代码。