TeX/LaTeX很棒,我在很多方面都使用它.它的一些优点是:
但另一方面,一些小事情并不那么好:
那么,是否存在LaTeX的继承者/替代品,或者至少是开发中替代品的热门候选者.一个真正的继承者/良好的替代品将保持优势并解决其中的一些缺点或至少其中一些缺点.
我试图找到使用ffmpeg C API的文档.似乎只有命令行文档可用.有没有好的文档/教程/链接？
我正在编写一个轻量级类,其属性旨在可公开访问,并且有时仅在特定实例中被覆盖.在Python语言中没有为类属性或任何类型的属性创建文档字符串的规定.记录这些属性的可接受方式是什么？目前我正在做这样的事情:
class Albatross(object):
"""A bird with a flight speed exceeding that of an unladen swallow.
Attributes:
"""
flight_speed = 691
__doc__ += """
flight_speed (691)
The maximum speed that such a bird can attain.
"""
nesting_grounds = "Raymond Luxury-Yacht"
__doc__ += """
nesting_grounds ("Raymond Luxury-Yacht")
The locale where these birds congregate to reproduce.
"""
def __init__(self, **keyargs):
"""Initialize the Albatross from the keyword arguments."""
self.__dict__.update(keyargs)
这将导致类的docstring包含初始标准docstring部分,以及通过扩充赋值为每个属性添加的行__doc__.
虽然在文档字符串样式指南中似乎没有明确禁止这种样式,但它也没有作为选项提及.这里的优点是它提供了一种方法来记录属性及其定义,同时仍然创建一个可呈现的类docstring,并避免编写重复来自docstring的信息的注释.我仍然有点生气,我必须实际写两次属性; 我正在考虑使用docstring中值的字符串表示来至少避免重复默认值.
这是否是对特设社区公约的毁灭性违反？好吗？有没有更好的办法？例如,可以创建包含属性值和文档字符串的字典,然后__dict__在类声明的末尾将内容添加到类和docstring中; 这样可以减少两次输入属性名称和值的需要. 编辑:我认为,这最后一个想法实际上是不可能的,至少不是没有从数据动态构建整个类,这似乎是一个非常糟糕的想法,除非有其他理由这样做. …
2015年8月更新: Pinterest现在提供它https://dev.pinterest.com/
是否有关于v2 Pinterest API的官方或非官方文档？
我知道的事情:
2014年3月4日更新 Pinterest推出了可以请求访问的beta v3 API.向下滚动页面,您将看到左栏中列出的端点. https://developers.pinterest.com/api_docs/
更新2013 年1月9日由于https://api.pinterest.com/v2给出了404,它似乎已被移至v3. https://api.pinterest.com/v3
{ "status": "failure", "code": 11, "host": "053", "generated_at": "Wed, 09 Jan 2013 10:25:27 +0000", "message": "API method not found.", "data": null }
2012年11月19日更新http://tijn.bo.lt/pinterest-api上 的非官方api文档以及整个网站都已消失.我将离开此帖子中的链接,因为它可能会重新上线.仍然没有Pinterest对开发人员的api状态.
更新2012年5月22日 Pinterest仍未提供公开API.人们正在将iPhone用户代理连接到api端点,该用户代理可供iOS应用使用
2012年4月17日更新 感谢tijn,我们有非官方版本1(现在是v2)Pinterest api文档,并且报告只有读取端点当前可用,因此可以在速率限制内使用RSS样式.
更新2012年4月3日 非官方的Facebook小组有一些质量信息,有几个人提问并发布相当有用的回复
我正在阅读Photoshop,Illustrator和InDesign的JavaScript脚本指南.API真的很难读,因为它假设我知道某些简写约定.问题不仅限于此特定脚本指南.我可以列出几十个出现同样问题的人.
当我将API作为一个24小时不在代码中的人阅读时,我想查看一些内容,并以最基本的形式查看代码的简单示例.但通常一开始就不容易理解它.
这是一个例子.我正在查找如何在Photoshop中通过JavaScript更改项目的颜色.所以我搜索PDF并找到"fillColor".我在文档中找到了这个:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
当我读到这篇文章时,乍一看毫无意义.为什么有括号,我怎么知道我不应该在实现中使用它们？为什么括号中有逗号？我知道从我找到的样本代码应该是什么样的,这是:
myPath.fillPath(myNewColor)
myPath.fillPath(mynewColor, {
mode: RGB,
opacity: .5
})
如果我没有看到这个例子,我绝对不会从API代码中看出这个方法在实现时的外观.其他人指出这个方法的扩展示例可能如下所示:
fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])
好.我看到我可以省略隐含的可选参数.精细.但同样,我绝不会从API中猜到这一点.
那么,某处是否有一些神秘的文件告诉人们如何阅读API文档？为什么这样写？我有什么先验知识？为什么会这样,我该怎么做才能停止对它的疑惑并"得到"它,所以我可以更乐意阅读并实现下一个API？
那么为什么API文档的编写方式会混淆像我这样的常年新手/黑客/ DIY玩家呢？
常识告诉Doxygen注释块必须放在头文件中,其中包含类,结构,枚举,函数和声明.我同意这是一个合理的论据,这些库意味着在没有源的情况下进行分发(只有头和带有目标代码的库).
但是......当我正在开发一个公司内部(或者作为我自己的副项目)库时,我一直在考虑完全相反的方法,该库将与其完整的源代码一起使用.我建议将大的注释块放在实现文件(HPP,INL,CPP等)中,以免混乱标题中声明的类和函数的接口.
优点:
缺点:
那么,您的想法和建议是什么？
是否有自动方式在界面与其实现之间同步注释？我目前正在记录它们,并且不想手动保持它们同步.
更新:
考虑以下代码:
interface IFoo{
/// <summary>
/// Commenting DoThis method
/// </summary>
void DoThis();
}
class Foo : IFoo {
public void DoThis();
}
当我创建这样的类:
IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense
这里的评论没有显示:
Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense
该<inheritDoc/>标签将完全产生沙堡的文件,但它并没有在智能感知提示工作.
请分享您的想法.
谢谢.
我有一个R使用的包roxygen2.它有一些C代码/src,我刚开始使用Doxygen.有没有办法组合文档,或集成编译与roxygen2？在哪里放置C代码文档的"最佳实践" ？
谷歌搜索roxygen2和doxygen主要导致roxygen类似于doxygen结果.我找到了一些包含Doxyfiles的软件包,但没有一致的组织.例如,lme4 inst/doc/Doxyfile输出到源目录doxygen外部的文件夹lme4.在Matrix的根目录中还有一个Doxyfile(但在以前的版本中是这样的inst.此文档也导出到包目录之外.
是否有任何理由不在C包中包含文档,或者为什么Doxygen在R包中很少使用,尽管广泛使用C？
更新:查看相关的roxygen2功能请求
请确定最流行的轻量级标记语言,并比较它们的优缺点.这些语言应该是技术散文的通用标记,例如文档(例如,Haml不计算在内).
我正在尝试在Python中进行一些类继承.我希望每个班级和继承的班级都有良好的文档字符串.所以我认为对于继承的类,我希望它:
在类继承情况下是否有任何(可能是优雅或pythonic)方式进行此类文档字符串操作？多重继承怎么样？