javadocs

JavaDoc源代碼嵌入很爛！

我喜歡JavaDoc，但年齡不理想。 當(dāng)您使用其他工具（例如，在Microsoft世界中）時(shí)，嵌入式示例突然變得驚人，并且內(nèi)置了“搜索”功能！

我們?yōu)槭裁床荒軗碛兴?#xff1f;

JDK 9 引入了對(duì)搜索的新支持，但源嵌入可以更好，并且是至關(guān)重要的學(xué)習(xí)工具……

由于文檔和適當(dāng)?shù)拇a示例至關(guān)重要，因此我們決定重新訪問(wèn)javadocs并從頭開(kāi)始，至此，我們創(chuàng)建了一個(gè)新的開(kāi)源項(xiàng)目： JavaDoc Source Embed 。

該項(xiàng)目的目標(biāo)是允許在JavaDoc中使用github“ gist”，它使您可以創(chuàng)建看起來(lái)像這樣的 JavaDoc，而不是通常貧乏的源代碼嵌入。

如果您不熟悉github gists，則其本質(zhì)上是一個(gè)代碼片段托管服務(wù)，該服務(wù)既可以很好地格式化代碼，又可以讓您輕松地通過(guò)github（叉，星，手表等）對(duì)其進(jìn)行維護(hù)。

中央托管是真正的“殺手級(jí)功能”，它使您可以將示例嵌入適用的所有位置，而無(wú)需復(fù)制和粘貼。 例如， LocationManager是保存樣本的好地方， Geofence類也是如此。 在這些情況下，我們只需要在Javadoc中復(fù)制以下小片段：

<script src="https://gist.github.com/codenameone/b0fa5280bde905a8f0cd.js"></script>

gist僅有的兩個(gè)問(wèn)題是它缺乏可搜索性，并且它不會(huì)出現(xiàn)在不呈現(xiàn)JavaScript的IDE中。 JavaDoc Source Embed項(xiàng)目通過(guò)自動(dòng)生成帶有最新版本的gist的“ noscript”標(biāo)簽來(lái)有效解決該問(wèn)題，從而使其在被引用的任何地方都可以正確顯示。

我們將嘗試更新我們的javadocs，但對(duì)于拉取請(qǐng)求和指向缺失示例以及應(yīng)將它們放置在代碼中的位置的問(wèn)題感到高??興。

開(kāi)發(fā)人員指南Wiki

在其他新聞中，我們剛剛完成了將開(kāi)發(fā)人員指南遷移到github Wiki頁(yè)面的工作，并且看起來(lái)已經(jīng)大不相同了。 使用githubs Wiki頁(yè)面的方法有其缺點(diǎn)，而asciidoc確實(shí)有一些痛點(diǎn)，但總的來(lái)說(shuō)，我認(rèn)為這是一個(gè)開(kāi)放項(xiàng)目的良好方向。

伊斯梅爾·鮑姆（Ismael Baum）進(jìn)行了許多Wiki編輯，修復(fù)了許多語(yǔ)法和邏輯錯(cuò)誤，并在此過(guò)程中發(fā)現(xiàn)了許多錯(cuò)誤！

除了為文檔進(jìn)行的許多重寫和修復(fù)之外，我們還編寫了一個(gè)腳本，該腳本將Codename One類名稱轉(zhuǎn)換為鏈接到JavaDoc。

因此，現(xiàn)在不僅要突出顯示LocationManager還應(yīng)該看到LocationManager更加有用。 請(qǐng)注意，這不應(yīng)影響代碼塊之類的內(nèi)容，僅提及特定類。 從這一點(diǎn)開(kāi)始，我們將嘗試將文檔互連以產(chǎn)生與文檔更加一致的體驗(yàn)。

我將開(kāi)放用于鏈接的腳本的源代碼，但是它主要是一堆非常特定的sed命令，可能對(duì)任何人都沒(méi)有用。 由于它是“一次性”腳本，因此我們不再運(yùn)行它，我們只需要保持鏈接繼續(xù)進(jìn)行即可。

反饋

您知道我們可以用來(lái)改善文檔狀態(tài)的其他工具嗎？

我們正在尋找當(dāng)前工具鏈上似乎仍然很難的幾件事：

• 更好的JavaDoc集成-將其嵌入到現(xiàn)有Web設(shè)計(jì)中的能力將是很棒的！ CSS太局限了。
• 改善asciidoc PDF的外觀–當(dāng)前，PDF在打開(kāi)頁(yè)面中看起來(lái)過(guò)于學(xué)術(shù)化，有一些解決方案，但大多數(shù)看起來(lái)有些拙劣。
• 語(yǔ)法和樣式工具–有一些不錯(cuò)的文字處理程序語(yǔ)法檢查器，但我們找不到適用于asciidoc的任何東西。 可以指出不清晰寫作的寫作分析工具也缺少同樣的東西。 我看到gitbooks那里有一些有趣的工具，但是我不確定我們是否要使用它。

讓我們知道您是否熟悉此類工具或我們可能不知道的其他內(nèi)容。

翻譯自: https://www.javacodegeeks.com/2016/01/javadocs-source-samples-dont-suck.html

javadocs

總結(jié)

以上是生活随笔為你收集整理的javadocs_不会吸引人的JavaDocs源样本的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。