标签: documentation

我终于开始学习Java了,我正在寻找一些可以下载和离线阅读的Java文档.像Sun的东西,但拉链或PDF或CHM.

我正在使用Eclipse,因此可以很好地集成Eclipse.它似乎已经有一些我想要的东西(javadoc的东西),但我没有看到如何搜索它,我没有看到语言参考.

我希望能够将Android api文档集成到Eclipse中,例如,如果将鼠标悬停在Activity类上,则会在弹出窗口中获得相应的Javadoc.

因此,要将Javadoc添加到Android,您需要在Eclipse中打开任何Android项目.定位"Android xx"库.在此右键单击android.jar文件并选择Properties.选择Javadoc位置条目.

在JavadocURL部分,我输入了http://developer.android.com/reference/packages.html并单击了Validate,但它给出了通常的错误

位置可能无效.尚未找到通常在Javadoc工具创建的文档的根目录中提供的文件'package-list'和'index.html'

我已尝试过该网址的大量变体,但无济于事.

我也不想不得不下载Android的源代码.

我想看看各个领域的评论.通常我会从"描述"参数中得到一些东西.

mysql> describe metrics;
+-------+---------------------+------+-----+---------+----------------+
| Field | Type                | Null | Key | Default | Extra          |
+-------+---------------------+------+-----+---------+----------------+
| id    | int(10) unsigned    | NO   | PRI | NULL    | auto_increment |
| ty    | int(10) unsigned    | NO   |     | NULL    |                |
| t     | bigint(20) unsigned | NO   |     | NULL    |                |
| s     | int(10) unsigned    | NO   |     | 60000   |                |
| e     | int(10) unsigned    | NO   |     | NULL    | …

我似乎无法弄清楚如何使用Sphinx记录异常.

我尝试过以下方法:

def some_funct():
    """
    :raises: ExceptionType: Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises: ExceptionType, Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises ExceptionType: Some multi-line
        exception description.
    """


def some_funct():
    """
    :raises:
        ExceptionType: Some multi-line
            exception description.
    """

斯芬克斯一直说"场名列表没有空白线;意外的不连贯." 那么我如何摆脱信息以及用多行文档记录可能的多个异常的正确方法是什么？

我有一个模块,有两个记录的全球特殊成员.

在本地运行Sphinx会创建包含其文档的文档,但"阅读文档"却没有.它使用内置类型的文档.

我尝试了两种样式:#:和定义后的docstring.我已多次阅读autodoc的文档,并阅读了文档条目.我无法弄清楚我缺少什么,因为我甚至没有看到阅读文档中的任何构建错误.

有任何想法吗？

我正在尝试将外部API的交叉引用添加到我的文档中,但我面临三种不同的行为.

我正在使用sphinx(1.3.1)和Python(2.7.3),我的intersphinx映射配置为:

{
'python': ('https://docs.python.org/2.7', None),
'numpy': ('http://docs.scipy.org/doc/numpy/', None),
'cv2' : ('http://docs.opencv.org/2.4/', None),
'h5py' : ('http://docs.h5py.org/en/latest/', None)
}

我可以毫不费力地编写numpy API的交叉引用,:class:`numpy.ndarray`或者:func:`numpy.array`像我们预期的那样给我一些像numpy.ndarray这样的东西.

但是,使用h5py,我可以生成链接的唯一方法是省略模块名称.例如,:class:`Group`(或:class:`h5py:Group`)给我Group但:class:`h5py.Group`无法生成链接.

最后,我找不到一种方法来编写一个工作交叉引用OpenCV API,这些似乎都没有工作:

:func:`cv2.convertScaleAbs`
:func:`cv2:cv2.convertScaleAbs`
:func:`cv2:convertScaleAbs`
:func:`convertScaleAbs`

如何正确编写对外部API的交叉引用,或配置intersphinx,以便在numpy情况下生成链接？

我是一个相对较新的开发人员,并被分配了记录由高级C#开发人员编写的代码的任务.我的老板告诉我要仔细查看,并记录下来,以便根据需要更容易修改和更新.

我的问题是:我应该遵循标准类型的文档/评论结构吗？我的老板听起来好像每个人都知道如何将代码记录到某个标准,以便任何人都能理解它.

我也很好奇是否有人有一个很好的方法来找出不熟悉的代码或功能不确定性.任何帮助将不胜感激.

我想为计算机视觉领域的项目,模块和库集合准备一份文档(主要用c ++编写).为此,我查看了OpenCV文档,您可能知道OpenCV 2.4.x文档基于Sphinx,这是我寻求的确切解决方案.Sphinx的优点是:

1. 从语义角度看模块的层次结构.例如,卡尔曼滤波器是运动分析和对象跟踪模块的子代
2. 您可以添加图像和数学公式
3. 相当不错的嵌入式搜索引擎

但我意识到OpenCV3.0的c ++版本是基于Doxygen记录的,我不知道为什么!因为它没有Sphinx那么有趣.我知道Doxygen可以编译你的代码并提取你的评论,这是一个有用的功能.我也知道有些库(如呼吸)可以作为Doxygen和Sphinx之间的桥梁.

现在我的问题是:

1. 彼此的Sphinx和Doxygen替代品还是可以和它们一起使用？
2. Doxygen是否具有Sphinx所提到的功能？
3. 您更喜欢哪个文档引擎(Sphinx,Doxygen或其他引擎)？

如何在Kotlin的默认文档工具KDoc中插入代码片段？

在Java中,我可以使用以下内容:

/**
 * Example usage:
 *
 * <pre>
 * <code>&#64;JavaAnnotation
 * public void foo() {
 *     // Code
 * }
 * </code>
 * </pre>
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface JavaAnnotation {}

Kotlin似乎没有相应的东西.我尝试使用Markdown,但在行结束后插入2个空格不会换行.

该描述对co_names在检查模块读取:

局部变量名称的元组

但实际上它似乎co_names是全局变量名co_varnames的元组,而是局部变量名(和参数名)的元组.例如:

a = 1

def f(b):
    c = a + b

print(f.__code__.co_varnames)  # prints ('b', 'c')
print(f.__code__.co_names)     # prints ('a',)

此外,在dis模块的文档中,许多指令描述意味着co_names包含全局变量的名称.例如,LOAD_GLOBAL 描述如下:

将全局命名的co_names [namei]加载到堆栈中.

我在这里误解了什么吗？是否co_names真的含有"局部变量的名字"？

编辑07/17/2017

如评论/答案中所述,这似乎是文档错误.Bug问题在这里提交.

编辑07/22/2017

拉请求修复此文档错误已批准并等待合并.