JavaDoc源代碼嵌入很爛！

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

我們為什么不能擁有它？

JDK 9 引入了對搜索的新支持，但是源嵌入可以更好，并且是至關重要的學習工具……

由于文檔和適當的代碼示例至關重要，因此我們決定重新訪問javadocs并從頭開始，到此為止，我們創建了一個新的開源項目： JavaDoc Source Embed 。

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

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

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

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

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

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

開發人員指南Wiki

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

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

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

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

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

反饋

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

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

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

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

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

總結

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

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。