教程的优雅代码注释？

我一直在写一些教程，并试图找出一个优雅的方式来添加逐行注释到教程中的代码。教程的优雅代码注释？

例如，假设我有一些像这样的代码：

<h1>Demo of web page</h1> 
<p>This is a paragraph</p>

我想能够添加一些东西（也许一个提示或某种收藏效果），让我提出一个解释每条线的读者，而仍然让他们看到上下文中的线。我能够想到的最好的是散文解释说，像“以<h1>开头的行是标题。”

任何人见过这样的事情？

来源

2011-12-07 pingswept

如何使用标题属性？

<h1 title="your hover text">your text</h1>

来源

2011-12-07 18:41:07

适用于html，但不适用于其他语言。而且，它使代码本身更加混乱。但是，谢谢你的建议。 – pingswept

你可能想看看docco：

http://jashkenas.github.com/docco/

这是写在CoffeeScript中，并生成从源文件分手的注释部分和代码的HTML文档。它将注释设置为一列中每个部分的注释以及另一列中相应的正确突出显示的代码。我认为这是一个非常简单的方法，可以在保持代码上下文的同时进行注释。哦，它也知道降价。

来源

2011-12-07 18:51:08 eliotk

哦，还有一个python端口：http：//fitzgen.github.com/pycco/ – eliotk

这几乎就是我正在寻找的东西。如果我走这条路线，我可能会使用Python端口Pycco。我不确定构建步骤会增加到我的网站的额外复杂性是否值得，但这是我见过的最好的。功能完全正确。谢谢，艾略特。 – pingswept

（刚刚看到你的Python端口评论，肯定！） – pingswept

我想我可能已经找到了对手Docco：Twitter的引导的酥料饼特点：http://twitter.github.com/bootstrap/javascript.html#popover

我不知道它实际上看起来不错，但它似乎是一个良好的开端。

来源

2011-12-07 23:32:20 pingswept

旧的但很好的问题，当我找到这个时，我正在寻找类似的东西。有很多方法可以做HTML注释，see this article for a very nice listing and explanations。

如果您想要注释只是告诉用户每一行的功能，我会为小块代码编写HTML注释，并为大量代码编写较大的外部注释。如果你愿意的话，你可以使用自定义JS来解析它们以显示漂亮的盒子。

<h1>Heading</h1> <!-- A heading element --> 
<p>paragraph</p> <!-- A paragraph element --> 
<p>Paragraph with 
    <b>Bold</b>  <!-- An inline Bold element --> 
text</p>

对于较大金额的代码，我会用海外商品会有这样的事情Docco创建的文档。当然，这是针对JavaScript的，但是谁说类似的不能用于HTML。由于这是用jquery-ui标记的，你也可能会在jQuery text annotater中加入。

来源

2012-07-30 06:06:06 Nenotlep

这对于你的类似碳的需求来说并不是一个真正的答案，但我认为它可以做DIY和不做，我还没有看过预制的 - 如果我有时间我会拼凑一些东西。 – Nenotlep

教程的优雅代码注释？

回答

相关问题