标签: documentation

好的，所以我有一个 .NET 控制台应用程序，它的 Main 方法包含在 Program 类中。你知道，通常的：

class Program
{
    static void Main(string[] args)
    {
        // Do something spectactular
    }
}

自从我开始如此严格地使用 StyleCop 和 FxCop 以来，我对确保所有内容都正确记录变得有点挑剔。

然后它击中了我。我完全不知道如何正确记录 Program 和 Program.Main。

我想，从长远来看，您可以采用以下方法：

/// <summary>
///     Encapsulates the application's main entry point.
/// </summary>
class Program
{
    /// <summary>
    ///     The application's main entry point.
    /// </summary>
    static void Main(string[] args)
    {
        // Do something spectactular
    }
}

但这似乎严重不足（尽管我的 Main 例程总是委托给其他类来完成这项工作）。

你们是如何记录这些事情的？有推荐或标准吗？

我一直试图在 Three.js 中找到一些关于粒子系统的很好的教程，但一直没有找到任何值得注意的东西。是否有一个易于使用的粒子引擎，也许有一些很好的介绍和文档？此外，在这些粒子系统中，我是否可以自由支配单个粒子的定位，还是完全随机？

您有没有办法在c#中为开发人员记录不可变类型的属性？

我知道您可以使用以下方法轻松记录类和对象:

  /// <summary>
  /// This is an object
  /// </summary>

但是如果我创建一个新对象,如何为popupmenu创建一个条目:

Myobject ob1 = new Myobject(x1,x2,.....);

我想要的是每个值的简短描述,例如"x1是我的对象的长度"和"x2是高度".另外我想添加一些响应的东西,例如,如果用户为x1输入"1",x2显示工具提示"长度",但如果用户输入"2"作为输入,则x2显示"高度"工具提示.

我习惯于以特定的方式记录C#项目中的代码,以提高团队生产力,从Visual Studio中的Intellisense等中受益.

代码看起来类似于:

/// <summary>
/// Loads a user with a specific id.
/// </summary>
/// <param name="id">The id of the user to search for.</param>
/// <returns>A user with the given id.</returns>
public User GetUserById(string id) {
    ...
}

用于评论和文档的Typescript是否有类似的约定？甚至是使用这些约定从代码注释(如JavaDoc)生成html文档页面的工具？

我有时会将函数调用及其输出的示例放在函数定义的文档字符串中.

(defun js-[] (&rest args)
  "Javascript array literal statement.
  (js-[] 1 2 3)
  > \"[1, 2, 3]\"
  "
  (format nil "[~{~A~^, ~}]" (mapcar #'js-expr args)))

但有时函数的输出是一个字符串.所以我必须在示例输出中转义双引号.这很快就变得单调乏味.

有没有办法将文档字符串分隔符从双引号更改为其他内容,以便我不必继续转义它们？

请注意,有时它比只逃避一次更糟糕:

(defun js-~ (str)
  "Javascript string statement. This is needed so that double quotes are inserted.
  (js-~ \"string\")
  > \"\\\"string\\\"\"
  "
  (format nil "\"~A\"" str))

这里还有一个问题.阅读文档很困难.

我正在尝试学习 Spark，到目前为止一切进展顺利，除了我需要在值为列表的一对 RDD 上使用像reduceByKey或combineByKey这样的函数的问题。

我一直在尝试找到这些函数的详细文档，这些文档可以解释参数的实际含义，这样我就可以自己解决它，而无需去 Stack Overflow，但我就是找不到任何好的 Spark 文档。我读过《Learning Spark》的第3章和第4章，但说实话，对于最复杂的函数的解释非常糟糕。

我现在正在处理的问题如下：我有一对 RDD，其中键是字符串，值是两个元素的列表，这两个元素都是整数。像这样的东西：（国家，[小时，计数]）。对于每个键，我希望仅保留计数最高的值，无论时间如何。一旦我有了上述格式的 RDD，我就会尝试通过调用 Spark 中的以下函数来查找最大值：

reduceByKey(lambda x, y: max(x[1], y[1]))

但这会引发以下错误：

TypeError: 'int' object is not subscriptable

这对我来说没有任何意义。我将参数 x 和 y 解释为两个键的值，例如 x=[13, 445] 和 y=[14, 109]，但错误没有任何意义。我究竟做错了什么？

我正在尝试编写一些POD文档并使用perldoc来显示它.我的目标是让格式看起来像这样:

REQUIRED ARGUMENTS
    argument1
        Description of the first argument. 

    argmuent2
        Description of the second argument.            

其中"REQUIRED ARGUMENTS"是粗体标题,"argument1"和"argument2"是斜体.

但我无法弄清楚如何获得特定的缩进.

我试过这个:

=head1 REQUIRED ARGUMENTS

I<argument1>
Description of the first argument.

I<argument2>
Description of the second argument.

产生以下内容(正确显示粗体标题和斜体,但不需要运行描述):

REQUIRED ARGUMENTS
    argument1 Description of the first argument.

    argument2 Description of the second argument.

我试过了:

=head1 REQUIRED ARGUMENTS

I<argument1>

Description of the first argument.

I<argument2>

Description of the second argument.

产生以下内容(粗体和斜体也很好,但现在参数和描述之间有一条额外的线):

REQUIRED ARGUMENTS
    argument1

    Description of the first argument.

    argument2

    Description of the second argument. …

文档中的解释对我来说不清楚。我的 api 文档渲染后没有看到任何差异。
视觉上有什么区别？从逻辑上讲，映射是做什么的？例如

MySchema:
  oneOf:
    - $ref: '#/componets/schemas/SubSchema1'
    - $ref: '#/componets/schemas/SubSchema2'
  discriminator:
    propertyName: some_property:
    mapping:
      TypeA: '#/componets/schemas/SubSchema1'
      TypeB: '#/componets/schemas/SubSchema2'

我在任何地方都找不到有关 C# 文档注释的答案，所以请解释一下：

如果我在 [someFunc()] 中有一个单独的类和一个方法，那么使用 /// Visual Studio 将插入该方法的文档注释。

namespace someNs
{
    internal class someClass
    {   
        /// <summary>
        /// 
        /// </summary>
        
        public void someFunc()
        {          
        }        
    } 
}

但是，如果我在“static void Main(string[] args)”中有一个方法，那么使用 /// 不起作用。

namespace someNs
{
    internal class Program
    {
        static void Main(string[] args)
        { 
            void someFunc()
            {
            }        
        }
    }   
}

请解释为什么会这样，是否可以通过某种方式添加文档注释？

谢谢。

我在使用javadoc时遇到了麻烦.它似乎既有用又极其愚蠢!我正在尝试为类编写多行描述:

/**
 * this is my class, there are many like it, but this one is mine!
 * 
 * blah blah blah
 *       - blah blah
 *       - blah blah
*/

但是当使用该类时,描述显示为单行blob!请告诉我,制作它的人比这更聪明,并且有一种方法可以让javadocs显示多行描述.

谢谢.

当我在Eclipse中查找Integer.class文件时,我可以找到getChars方法:https://imgur.com/CPD68sA

但在官方Java文档中没有getChars方法:https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html

为什么？

我确实看到了函数 Math.ceil(double a) 的以下描述（在文档中）：

返回大于或等于参数且等于数学整数的最小（最接近负无穷大）双精度值。

我在这里“返回最小的（最接近负无穷大）”中是否遗漏或不正确？我的意思是，当你使用它时，无论小数点后的数字不是零，它总是会以正方向而不是负方向向上（因此它返回最接近正无穷大）。