这篇文章讲的是什么？总是写文档。不写，代码维护不了，只好自己写。但是写文档又费时又费力。更可怕的是，写完了再看还是很吃力，总觉得时间浪费了。被“写文档”折磨了很久。偶然看到一篇神文，然后上网查了一下自动化工具和DSL的理论。然后我恍然大悟！虽然大部分看不懂，但是如果你想轻松写出好的文档，这就够了！现在让我们谈谈我是如何做到的！做什么我们的最终目标是编写好的文档。所以，首先我们要确定：什么是好文档。一个好的文档如下图所示：上面的文档有什么好？第一，它是一个文档，让你一眼就知道它的功能和参数；第二，它是一个程序，输入参数就可以看到结果。因此，我希望的是，在完成代码后，我可以毫不费力地生成一个像上面提到的可调试文档。接下来我们要做两件事：1.生成文档；2.文件为可调试文件。怎么做？既然要开始做，总觉得无从下手，那我们就从最具体的——目前唯一可见的可调试API说起吧。我们到底要做什么样的可调试API呢？参考之前的效果图，为了简化，它看起来是这样的：纯文本显示类名、方法、函数解释和输入参数；有一个执行按钮；有一个区域显示执行结果。在这个界面中，变量是什么？类名列表Item方法名功能描述参数数量参数名执行结果其中：一个API对应一个类名，一个方法名，一个函数描述，多个参数名，执行后产生执行结果。模型分析根据上面的结果，我可以把这个API抽象成一个模型类：一个API包括属性：类名、类文件路径、方法名、功能描述、方法需要的参数。而一个参数包含属性：参数名称和参数描述。事件流程接下来分析整个交易流程。一句话流程：点击“Generate”按钮，生成该类的HTML文档。这就是我们要做的，但还很不明确。我们想生成一个HTML文档对应某个类的某个方法，但是没有明确的语句。现在我们要解释清楚，所以我们把它展开，变成一段：配置文件已经指定了要生成的类及其方法，点击“生成按钮”，读取配置文件，然后生成文档反过来。我们将继续这样扩展，直到我们弄清楚所有步骤。整个系统最终设计的页面分为三类：类列表页面：列出类及其方法，点击后跳转到API页面。API页面：列出方法描述，可以输入参数并执行方法，可以查看其执行结果。三种页面中，第二种列表页没有任何功能，只涉及页面跳转，所以只能用html实现。至于功能页面和API页面，都是MVC模式设计的。功能页面MVC结构模型：API；查看：make_api_template.php；Controller：create_api.phpMVC调用流程用户点击View层的“Generate”按钮后，Controller被触发；Controller指定需要生成API的类，并调用这些类的静态方法make_api生成Model；Controller使用这些Models生成文档API页面MVC结构Model：js代码，尚未形成独立模型；View：生成的html页面；Controller：index.phpMVC调用流程用户在View层输入一个方法的参数，点击“Execute”按钮后触发Controller；Controller根据View页面传来的参数执行方法，并将结果返回给View；视图接收结果并显示它。结论我实现的版本是CohenBible。类似的工具还有很多，比如prmd、swaggereditor、apidocjs，都非常好用。写这篇文章并不是鼓励大家去重新发明轮子，但是如果你自己去实现，你会得到不同的结果。为什么我会想到重新发明轮子？其实最大的原因是：我实在不会用上面的工具，只好自己实现，走一遍生成文档的全过程。结果，回过头来看上面的工具，原来是可以用的！如果按照官方教程来，不知道要花多少时间，哈哈:)
