Argot

从代码库解析文档到markdown，以便轻松创建文档。Argot 受传统JavaDoc系统的启发。

动机

维护不同语言的庞大系统会带来一系列独特的挑战，尤其是在维护这些系统的文档时。不同的文档系统会降低代码库的整体质量，同时阻碍开发者的生产力。Argot试图通过提供一种可以支持任何语言的单一文档风格，并将生成的文档输出为Markdown来解决这个问题。

名字的由来？

argot 的定义是 "某个群体或阶层的行话或俚语"。这似乎是一个相当合适的文档系统的名字。

警告

这仍然是一个正在进行中的项目，所以有些东西可能会出错。提交一个错误报告是我识别问题的最佳方式。

Argot 实际应用

查看 Argot 的 Wiki，其中Argot在此仓库上运行。

安装（使用）

使用Cargo安装

cargo install argot

安装（开发）

• 克隆仓库
• 确保已安装Rust / Cargo
• 在命令行 ...

cargo build

cargo run -- --help

构建发布版本

cargo build --release

命令行参数

Argot 0.2.0
Steven Hanna <steventhanna@gmail.com>
Parse documentation from codebases into Markdown for easy doc creation.

USAGE:
    argot [FLAGS] --destination <DESTINATION> --origin <ORIGIN>

FLAGS:
    -h, --help         Prints help information
    -r, --recursive    Recursively walk the file tree parsing
    -V, --version      Prints version information

OPTIONS:
    -d, --destination <DESTINATION>    Sets a custom destination path for rendered markdown files
    -o, --origin <ORIGIN>              Sets the origin of where Argot should start parsing from

示例

argot -o /src -d /docs -r

Markdown

所有支持的语言

系统正在设计为根据提供的注释风格调整解析。无论是用于Java或C这样的基于斜杠的语言，还是Python或Haskell等其他注释系统。我们不会为抽象类设计特定的语言类并填充抽象类提供的空缺，而是通过简单的构造函数提供新的语言。

所有标签都必须包含一个 类型 标签。

Java、Rust、C++、JS

/**
* @type :: FUNC
* @name :: test
*/

Python

'''
@type :: example
@name :: test
@end
'''

注意：文档中可以包含Markdown，并在最终页面上渲染。

类型

• FUNC - 函数或方法的标签
• VAR - 变量的标签
• CLASS - 类的标签

文件开头

在文件开头，您可以在类开始处使用以下任何组合，在声明之前。

@名称 :: - 文件的类名

@description :: - 对整个项目而言，文件所执行功能的描述

@date :: - 文件最后修改的日期

@version :: - 文件的当前版本

@author :: - 文件的作者。多个作者应以逗号分隔

@see :: - 提供到另一文件的参考链接

@child :: - 指示类的子类。多个子类应各自拥有自己的 @child 标签

@parent :: - 指示类的父类

@note :: - 记录与文件相关的任何重要信息

Java

/**
* @type :: CLASS
* @name :: Example File
* @author :: Steven Hanna, Other People
* @date :: 7/25/16
* @version :: 0.1.0
*/

Python

'''
@type :: CLASS
@class :: Example File
@author :: Steven Hanna, Other People
@date :: 7/25/16
@version :: 0.1.0
'''

方法

注意： 不分析方法的实际主体，只分析注释文档。

@name :: - 方法的名称。

@description :: - 方法的描述，相对于类的其他部分。描述可以跨越多行

@author :: - 方法的作者

@date :: - 方法最后更新的日期

@param :: - 方法接受的参数之一。对于每个参数，使用一个新的 @param

@return :: - 方法的返回值。如果是 void，则省略此文档。

@exception :: - 可能从该方法抛出的异常

@thrown :: - 可能从该方法抛出的错误

@see :: - 提供到外部文档的链接

@note :: - 记录与该方法相关的任何重要信息

/**
* @type :: FUNC
* @name :: sampleMethod
* @description :: Provides a sample method for this example.
* Overflow text can continue here
* @param :: String text - text to be returned
* @return :: String text - text that is returned
*/
public String sampleMethod(String text) {
  ...
  return text;
}

变量 / 实例变量

与方法一样，变量的文档必须在变量声明之前开始。变量应在声明时进行文档记录。

@name - 实例变量的名称

@description - 变量的描述，相对于类的其他部分

@see - 提供到外部文档的链接

/**
* @type :: VAR
* @name :: exampleInt
* @vartype :: the type of the variable
* @description :: example integer variable
*/
private int exampleInt;