Ruby：如何正确有效地写评论？

我正在阅读一个名为Mailchimp的Ruby API包装器的代码。我将在我的问题下面发布一个片段

除了代码之外，这些评论还引起了我的注意。发生这种情况有两个原因：

注释似乎有一个样式约定，特别是对于调用外部api的方法。我从B.Batsov那里了解了Ruby风格的约定，B.Batsov还有一个关于注释的部分。但这一部分相当简短，甚至与我在研究的代码中看到的内容不太接近

评论构成了正文的大部分，并提供了有关的详细信息 参数和返回值包括描述性文本 我的问题是，是否有一个关于如何呈现所有这些信息以及从何处获取这些信息的约定？这是手写的还是有办法从某处提取

以下是我正在学习的代码片段：

        # Get the content (both html and text) for a campaign either as it would appear in the campaign archive or as the raw, original content
        # @param [String] cid the campaign id to get content for (can be gathered using campaigns/list())
        # @param [Hash] options various options to control this call
        #     - [String] view optional one of "archive" (default), "preview" (like our popup-preview) or "raw"
        #     - [Hash] email optional if provided, view is "archive" or "preview", the campaign's list still exists, and the requested record is subscribed to the list. the returned content will be populated with member data populated. a struct with one of the following keys - failing to provide anything will produce an error relating to the email address. If multiple keys are provided, the first one from the following list that we find will be used, the rest will be ignored.
        #         - [String] email an email address
        #         - [String] euid the unique id for an email address (not list related) - the email "id" returned from listMemberInfo, Webhooks, Campaigns, etc.
        #         - [String] leid the list email id (previously called web_id) for a list-member-info type call. this doesn't change when the email address changes
        # @return [Hash] containing all content for the campaign
        #     - [String] html The HTML content used for the campaign with merge tags intact
        #     - [String] text The Text content used for the campaign with merge tags intact
        def content(cid, options=[])
            _params = {:cid => cid, :options => options}
            return @master.call 'campaigns/content', _params
        end

这是中的文档

✓

这是手写的还是有办法从某处提取

它是手写的，因为我几乎无法想象它可以从何处提取。

这是中的文档

✓

这是手写的还是有办法从某处提取

---

这是手写的，因为我几乎无法想象它可以从何处提取。

谢谢您的帮助。由于注释中的信息非常简单，并且描述文本来自API的文档，我认为可能有一种方法可以从API中获取它？如果这些信息可以在原始API文档中看到，为什么会有人费劲地复制和粘贴这些信息（这可能会产生一些错误）？您在原始API文档中看到的是，它是根据这些注释按码生成的。注意：一些IDE，例如，可以自动创建部分码文档块。但大多数类型，尤其是参数/返回值类型，都必须手动键入，因为它们不能从code.Thx中推断出来以帮助解决问题。由于注释中的信息非常简单，并且描述文本来自API的文档，我认为可能有一种方法可以从API中获取它？如果这些信息可以在原始API文档中看到，为什么会有人费劲地复制和粘贴这些信息（这可能会产生一些错误）？您在原始API文档中看到的是，它是根据这些注释按码生成的。注意：一些IDE，例如，可以自动创建部分码文档块。但大多数类型，尤其是参数/返回值类型，都必须手动键入，因为它们不能从代码中推断出来。