教程的優雅代碼註釋？

我一直在寫一些教程，並試圖找出一個優雅的方式來添加逐行註釋到教程中的代碼。教程的優雅代碼註釋？

例如，假設我有一些像這樣的代碼：

<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

教程的優雅代碼註釋？

回答

相關問題