我使用JSDoc来记录我写的所有JS，但我很好奇人们如何记录他们的文章。我想我可以使用JSDoc，但它看起来并不正确，因为JS不是很少。如果有一种标准方法可以允许不同的IDE提供工具支持，我还想避免使用JSDoc来记录我的文档。
有没有人知道标准的记录方式较少？
答案 0 :(得分：2)
记录源代码涉及不同的问题，可能有不同的目标，而不是记录CSS，无论是LESS还是其他任何变体。
源代码涉及涉及合同的类和方法，例如参数和返回值的类型和含义。它也可能具有复杂的逻辑，需要解释，或处理多个条件，或处理各种边缘情况。它可能正在实现一个第三方将使用的API，它应该有自己的独立文档，可以阅读＆＃34;。像JSDoc这样的系统在设计时充分考虑了这一切。阅读代码的人可以很容易地理解各种例程的目的和签名以及逻辑，和可以将注释处理成API文档。
类似地，源代码通常在逻辑上组织成模块和类的层次结构。在阅读文档时，想要从子类的描述跳转到其超类的描述，或者直到模块级别，这是很常见的。像JSDoc这样的工具也可以通过吐出多组相互关联的HTML页面来实现这一点。
另一方面，考虑一个像Underscore这样的库，只适用于上面的某些部分。没有模块，类或类层次结构。相反，它是一袋工具。因此，实际上不需要很多类似JSDoc的机器。相反，我想要做的是能够阅读代码并轻松查看正在发生的事情，或者获得有关所提供功能的叙述，可能还有一些代码示例。这就是他们使用Docco的原因，正如评论者所推荐的那样。它非常适合。正如评论者还提到的，它几乎可以用于任何编程语言，包括CSS。
与＆＃34;语言相比＆＃34;像JavaScript一样，CSS（通常）更平坦，并且没有＆＃34; contract＆＃34;的概念。参数和返回值，以及复杂的计算，虽然在像LESS这样的系统中，你有混合和计算。使用CSS，你也会遇到这样的情况：在很多情况下，CSS的效果是可视化的，比如说按钮以某种方式用特定大小的文本着色。我们在CSS中有两个潜在的评论消费者：实际上正在查看CSS代码的程序员，以及想要知道定义了哪些样式的UI设计者或实现者，并检查它们的工作方式。
就个人而言，我会在这里采用两种方法，映射到两种类型的消费者。在CSS代码本身中，我只是简单地用叙述来评论，描述规则的目的和结构。与此同时，我建立了一个单独的＆＃34;风格指南＆＃34; site，其中包含所有样式的可视示例。已经进行了各种尝试来自动化这种风格指南的创建，并取得了不同程度的成功。我没有使用它们，所以不能说它们有多么有用。就个人而言，我会选择一个手卷式指南。
值得指出的是，唯一比没有文档更糟糕的是错误的文档。无论您采用何种文档方法，您都必须确保它具有可持续性和可维护性。从这个意义上说，更简单就更好了。
最后，请注意，对广泛文档的需求与一组样式和类的设计精确度成反比。关于巴洛克式设计的论文没有太多意义，这些设计具有较差的类别，奇怪的依赖性和较差的命名，以及大量的文档。相反，您可能希望专注于重构CSS，以便至少进行一些自我记录。