标签: documentation

我不确定这里的最佳实践是什么,但我经常看到缩写变量名称,尤其是当范围很小时.所以(使用简单的Ruby示例)而不是def add_location(name, coordinates),我看到类似的东西def add_loc(name, coord)- 我甚至可能会看到类似的东西def add_loc(n, x, y).我想,当他们习惯于看到缩写词时,较长的名字可能会让一个人厌倦.

冗长是否有助于提高可读性,还是只会伤害每个人的眼睛？ - 人们更喜欢缩写和缩短名称吗？

因此,最近有消息称微软Skydrive每个帐户的存储量将达到25GB,有没有人知道SkyDrive是否有API？

(如果是这样,文档在哪里？)

在Sphinx中,如果我有以下标题声明:

.. _somestuff:

``this is code``, this is not!
==============================

它渲染,像这样:

    this is code, 这不是!

哪个好,但是,如果我使用参考,例如:

Have a look at :ref:`somestuff`

它丢失了代码格式并呈现如下:

    看看这是代码,这不是!

代替:

    看看this is code,这不是!

是否可以在引用中保留代码格式？我该怎么办呢？

我想知道是否有办法扩展文件中包含的标题下的所有子部分index.rst？

举个例子,它是这样的:

Section 1
Section 2
Section 3

以下是我希望如何:

Section 1
  Subsection 1.1
  Subsection 1.2
  Subsection 1.3
Section 2
  Subsection 2.1
  Subsection 2.2
  Subsection 2.3
Section 3
  Subsection 3.1
  Subsection 3.2
  Subsection 3.3

如果我点击第1部分,它会显示下面的内容,但是如果我点击第2部分,则隐藏第1部分的内容,只显示2.我想在每次进入索引页面时扩展所有2个部分.我试过加toctree和maxdepth,没有什么作品.

在C#文档标签中,您可以生成类似于MSDN的输出.在类,方法和属性上面的///(三次斜杠)注释区域内使用的允许标记列表是什么？

我知道PHP代码内联文档有许多不同的标准.这就是我对内联文档的意思,如果有更好的术语,请纠正我:

/**
* This is the description for the class below.
*
* @package    my-package
* @subpackage my-subpackage
* @author     my-name
* @version    my-version
* ...
*/
class orderActions {
...

什么是最好和最广泛接受的内联文档形式？是否有任何工具可以自动生成此类文档,还是必须手动完成？

我对生成手册不感兴趣 - 我想知道如何生成上面注释的代码类型,或"内联文档".

在官方的Microsoft文档中,只有一个段落提到了控件对键盘的行为(至少我能找到的):

http://msdn.microsoft.com/en-us/library/cc189015(v=VS.95).aspx#inputting_text

文本输入和控件

某些控件通过自己的处理对键盘事件做出反应.例如,TextBox是一个控件,用于捕获然后直观地表示使用键盘输入的文本,它在自己的逻辑中使用KeyUp和KeyDown来捕获击键,然后在文本中引发自己的TextChanged事件.实际上改了.您仍然可以将KeyUp和KeyDown的处理程序添加到TextBox或任何旨在处理文本输入的相关控件.但是,作为其预期设计的一部分,控件可能不会响应通过键事件定向到它的所有键值.行为特定于每个控件.例如,ButtonBase(Button的基类)处理KeyUp,以便它可以检查SPACEBAR或ENTER键,为了引发Click事件,它认为相当于鼠标左键按下.事件的处理是通过ButtonBase覆盖虚拟方法OnKeyUp来完成的,并且在其实现中它设置Handled = true.结果是,在空格键的情况下,监听键事件的按钮的任何父节点都不会为其自己的处理程序接收已处理的事件.另一个例子是TextBox.诸如ARROW键之类的某些键不被TextBox视为文本,而是被视为特定于控件UI行为,而TextBox将这些事件案例标记为已处理.结果是,在空格键的情况下,监听键事件的按钮的任何父节点都不会为其自己的处理程序接收已处理的事件.另一个例子是TextBox.诸如ARROW键之类的某些键不被TextBox视为文本,而是被视为特定于控件UI行为,而TextBox将这些事件案例标记为已处理.结果是,在空格键的情况下,监听键事件的按钮的任何父节点都不会为其自己的处理程序接收已处理的事件.另一个例子是TextBox.诸如ARROW键之类的某些键不被TextBox视为文本,而是被视为特定于控件UI行为,而TextBox将这些事件案例标记为已处理.

自定义控件可以通过重写OnKeyDown/OnKeyUp为键事件实现自己类似的覆盖行为.如果您的自定义控件处理特定的加速键,或者具有与TextBox描述的场景类似的控件或焦点行为,则应将此逻辑放在您自己的OnKeyDown/OnKeyUp覆盖中.

在任何地方都有更完整的参考吗？

例如,在AutoCompleteBox中,您可以导航到按向上/向下的建议,并选择按下输入等等.

当然必须有一个更好的方法,而不是集中每一个控件并按下键盘上的每一个键来找出:)

在Python中,您可以使用使用访问对象的文档字符串obj.__doc__.Ruby中的等效动作是什么？

我有一个开源项目(这里),其文档目前是法语.使用Sandcastle从代码中的XML注释生成文档.现在我想将文档翻译成英文并提供两种语言的文档,但我真的不知道从哪里开始...

• 我是否需要从代码中提取XML注释并将它们放在单独的文件中？如果是,是否有任何工具可以自动化该过程？
• 我正在使用Sandcastle帮助文件生成器来构建文档; 我是否需要创建一个单独的项目来构建英文文档,还是可以从同一个项目中完成？
• 在翻译过程中是否有任何工具可以帮助您？例如并排显示原始和翻译的文档？

我也对如何制作多语言文档的链接感兴趣,因为我在Google上找不到任何有用的东西......

我正在寻找一个可以帮助我生成RESTful API文档的工具.我的服务器是用Java编写的,并使用Spring MVC框架.我的服务器中没有VIEWS.它是一个100%RESTful服务,它所做的只是消耗JSON并吐出JSON.

我想知道Swagger是否与Spring注释兼容？