标签: documentation

我正在使用SpringFox (Swagger)来记录我的 REST API。Swagger 的一大优点是显示示例模型和数据类型格式。

现在，我将 API 配置为以毫秒为单位生成和使用日期，但当我查看示例 JSON 模型时，日期格式如下："2015-09-21T00:51:32.617Z"。请参阅下面的屏幕截图。是否可以告诉 SpringFox (Swagger) 如何正确格式化日期？

我正在扩展UIColor，并试图对扩展类进行描述。

我的代码是

/**
 - To store all colors
 - Naming Convention identifier: In lowerCamelCase with single name description
 - Naming Convention value: single name

 - example:  self.view.backgroundColor = UIColor.View.NonCompliant

 */
extension UIColor{

        /**
         - To specify all seperators' color
         */
        struct Seperators{
            static let commonSeperator = UIColor(red: 53.0/255.0, green: 126.0/255.0, blue: 167.0/255.0, alpha: 1.0)
        }
}

但Xcode仍然显示原始描述而不是修改后的描述。

有谁知道如何做到这一点？

我需要使用 JSDoc 来使sock变量data已知

var exec = {
    /**
     * @param {Number} sock
     * @param {String} data
     */
    1: (sock, data) => {
        console.log("GG");
    },
    2: (sock, data) => {

    },
    3: (sock, data) => {

    }
};

假设sock是Number，data是String。

/**
 * @param {Number} sock
 * @param {String} data
 */

我只需为整个对象设置 JSDoc 一次。

传入的“菜鸟”问题：

Javascript 有一个includes数组方法。

看起来像：

Array.includes()

但是，当我转到Javascript 手册来了解此方法时，该页面上的标题（我意识到出于适当的技术原因）是：

Array.prototype.includes()

Javascript 手册中的类似内容导致我根本不喜欢该手册（唉，我比手册更依赖 W3Schools）。

不过，我真的很想学习解读手册。

所以，我的问题是：当实际用法如下所示时，在文档中包含单词.prototypein的意义是什么？Array.prototype.includes()Array.includes()

（另外，如果有人对我如何提高对官方 Javascript 手册的理解有任何建议，我将不胜感激。）

我在字典中使用枚举：

Parameters = {
    ONE: Enum(
        value = 'Options',
        names = [
            ('SEPARATE', 0b1),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

这种风格的作品非常适合我的需求。

但是，当以不同的方式使用枚举时，我可以添加文档字符串：

class ONE(Enum):
    SEPERATE = 0b1
    """The registers associated with each port are separated into different banks"""
    SEQUENTIAL = 0b0
    """The registers are in the same bank (addresses are sequential)"""

那么我的问题是：

如第一个示例所示，在字典中使用枚举时如何添加文档字符串？

更新 测试枚举

Parameters = {
    'ONE': Enum(
        value = 'ONE',
        names = [
            ('SEPARATE', 0b1),
            ('SEQUENTIAL', 0b0)
        ]
    )
}

print(Parameters['ONE'].SEPARATE)

按预期工作

然后尝试扩展 Enum()

class NewEnum(Enum):
    def __init__(self, …

我正在使用 dbt docs generated 来生成我的项目的文档网站。我想用网站中我自己的自定义内容覆盖默认概述页面。可以这样做吗？

我正在尝试为我们正在集成的应用程序中的某个供应商提供的Web服务编写一些文档.一堆接口是Web服务本身定义的自定义对象.供应商已经对提供此应用程序的任何文档提出了很大的阻力,所以我已经把它自己做为他们的工作[反对我更好的判断].

他们的文档都坦言提供的是令人尴尬,我试图让本作短暂工作,因为我可能可以把一些质量好的文档在一起.我知道,由于我无法访问他们的源代码,我不能通过nDoc/Sandcastle运行它来吐出API文档,但我想知道是否(作为一个中途的房子)有一个简单的方法将intellisense导出到文本文件而不必编写实用程序来特定地迭代定义的每个对象类型并将成员反映到文本中？

如果我能做到这一点,至少可以确保我有一个高质量的文档结构,我可以填写空白.必须来回跳过Visual Studio来检查每个类成员的intellisense是一种非常费力的方法.

有没有人有任何想法？

在应用装饰器后,如何让函数中的帮助字符串保持可见？

现在,doc字符串被(部分)替换为装饰器的内部函数.

def deco(fn):
    def x(*args, **kwargs):
        return fn(*args, **kwargs)
    x.func_doc = fn.func_doc
    x.func_name = fn.func_name
    return x

@deco
def y(a, b):
    """This is Y"""
    pass

def z(c, d):
    """This is Z"""
    pass

help(y) # 1
help(z) # 2

在Y函数中,帮助中不显示必需的参数.用户可以假设它接受任何参数,而实际上它没有.

y(*args, **kwargs) <= y(a, b) is desired
    This is Y

z(c, d)
    This is Z

我用help()和dir()了很多,因为它比PDF手册快,想为我的图书馆和工具,可靠的文档字符串,但这是一个障碍.

在普通的类方法中,我可以在MATLAB中为"help"命令提供内容.但是,在编写抽象方法时,帮助函数不会看到抽象方法.例如,如果您有一个NeedsHelp类:

classdef NeedsHelp
    methods (Abstract)
        INeedHelp(self)
        % This method is not visible to the help command.
    end
    methods
        function IHaveHelp(self)
            % This method shows help as expected.
        end
    end
end

help命令的行为如下(R2009b):

>> help NeedsHelp.IHaveHelp
  This method shows help as expected.

>> help NeedsHelp.INeedHelp

NeedsHelp.INeedHelp not found.

有没有为抽象方法提供文档的解决方案？

关于C++中const和非const方法之间的区别,我有几个问题.

例:

      MyObject* MyClass::objectReference()
const MyObject* MyClass::objectReference() const

我的问题是:

1. 有没有办法区分手动调用哪个版本的方法？或者它是完全/完全自动的,如果是,那么确定调用哪个版本的准确规则是什么？
2. 与(1)相关,如果你不能区分调用const和非const版本,那么就不可能从另一个版本调用一个方法版本来防止重复？
3. 如何在使用doxygen的方法的文档中创建一个版本或另一个版本的链接？(例如"myMethod()的const版本."或"myMethod()的非const版本.") 我自己发现了 - 只需在方法签名的末尾添加或省略"const".