JavaDoc源代碼嵌入很爛！

我喜歡JavaDoc，但年齡不理想。 當(dāng)您使用其他工具時（例如在Microsoft世界中），突然間，嵌入式示例看起來很棒，并且“搜索”功能已內(nèi)置！

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

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

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

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

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

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

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

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

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

開發(fā)人員指南Wiki

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

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

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

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

我會開源用于鏈接的腳本，但是它主要是一堆非常特定的sed命令，可能對任何人都沒有用。 由于它是“一次性”腳本，因此我們不再運行它，我們只需要保持鏈接繼續(xù)進行即可。

反饋

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

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

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

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

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

總結(jié)

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

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