我正在寻找关于Javascript引擎内部的书籍/文章/论文,以及关于JVM内部,CLR内部等的许多参考书.我可以(并且可能会)查看JavaScriptCore和V8/Chromium的源代码,但如果那里有一本书或其他"导游"文档,我宁愿先阅读它们.谢谢.
所以我正在使用WCF,并希望记录我的界面和服务,以便为另一家公司提供内部应用程序.记录这些界面的最佳方法是什么？我更喜欢将文档与代码内联,然后对输出HTML有一些美化,但我不确定是否有推荐的方法来实现它.
我负责找到一个很好的方法来记录我正在进行的软件项目.
记录哪些内容很重要？代码和设计的文档是否应该以注释的形式出现在代码中？我们应该将文本文件或Word文档直接放在源代码控制中以便与代码一起使用吗？我们应该使用维基吗？
要考虑的因素包括当前团队创建文档的难易程度,以及其他开发人员以后查找,更正和扩展文档的难易程度.我从许多项目中获得的经验是开发人员倾向于不编写文档,因为编写文档的系统过于复杂或开发人员不友好,而且几年之后,新开发人员很难找到编写的小文档.
我对您在类似项目中使用的方法感兴趣.什么运作良好,什么运作不好,为什么？
关于该项目的一些关键事实:
这不仅仅是一个编码风格的问题.如果您了解python(我认为Ruby也有类似的东西),您可以在函数中使用docstring,这样您就可以通过发出"help"命令轻松获取该字符串.例如:
def something(t=None):
'''Do something, perhaps to t
t : a thing
You may not want to do this
'''
if t is not None:
return t ** 2
else:
return 'Or maybe not'
然后help(something)返回以下内容:
Help on function something in module __main__:
something(t=None)
Do something, perhaps to t
t : a thing
You may not want to do this
R中的工作方式,你可以获得定义的代码片段的全文,这样你就可以看到注释(包括函数开头的注释),但这可能是很多滚动和可视化过滤.有没有更好的方法？
使用Sphinx生成文档时,我希望能够生成两个版本的文档:一个包含所有内容,另一个只包含一组特定页面.实现这一目标的最佳方法是什么？
我可以编写一个构建脚本来移动文件来实现这一点,但如果有一种方法可以告诉sphinx在特定构建期间排除或包含特定文档,那将会非常好.
Apple最近发布了命令行工具:
Command Line Tools包中提供了哪些工具？
除了手册页之外还有某种文档吗？
请注意,我已通过在Xcode中添加特定组件来安装这些工具.此外,这不是关于Xcode项目,而是Apple于2012年2月16日发布的软件包!
过去在这个主题上有几个主题,声称Sphinx根本不支持这个.我有疑虑,但要么它已经更新,或者它的文档被很好地隐藏了,因为这里有一个链接在网站上另外说明: http://sphinx.pocoo.org/latest/domains.html#array:牛逼:::标-operatorC
无论如何,我是Sphinx的新手,但我正在尝试使用它(最终)使用来自某些源C++代码的一些文本来自动化文档.到目前为止,当使用sphinx-apidoc -o .......命令时,我无法到达任何地方.创建了几乎空白的文档.我可能没有使用正确的指令,因为我不知道如何 - 支持文档无法帮助我.
任何人都可以提供一些帮助来完成它的工作所需的基本步骤吗？如果无法从C++自动生成文档,那么C++域是什么以及如何使用它们？
我的Web api项目中有不同的插件和自己的XML文档,并且有一个集中的帮助页面,但问题是Web Api的默认帮助页面仅支持单个文档文件
new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/Documentation.xml"))
如何从不同的文件加载配置？我想这样做:
new XmlDocumentationProvider("PluginsFolder/*.xml")
asp.net documentation asp.net-web-api asp.net-web-api-helppages
我正在编写一个包,以方便进口巴西社会经济微观数据集(人口普查,PNAD等).我预见该包的两个不同用户组:
巴西的用户可能会对使用葡萄牙语的文档感到更放心.可能在某种程度上可以理解英语,但是外语可能会使包装感觉不那么"符合人体工程学".
更广泛的国际用户社区,英语文档可能是必要条件.
是否可以以文档"双语"(英语和葡萄牙语)的方式编写包,并且向用户显示的语言将取决于他们的国家/语言设置？
也,
这在roxygen2文档框架中是否可行？
我意识到,通过使包装更加复杂和难以维护,使包装更加用户友好是一种权衡.从以前的经验来看这种权衡的一般评论也是受欢迎的.
编辑:根据评论的建议,我交叉发布了r-package-devel mailling list.在这里,然后按照底部的答案.Duncan Murdoch发布了一个有趣的答案,内容涵盖了@Brandons回答(贝娄)的一些内容,还包括我认为有用的两个额外建议:
有一种语言的包,但不同语言的插图.我会遵循这个建议.
必须使用软件包的版本,比方说1.1和1.2,每种语言一个