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