Question

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

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

注释似乎有一种样式约定，特别是对于调用外部api的方法。我知道来自B.Batsov的像this one这样的Ruby样式约定，它也有一个关于注释的部分。但是这一部分相当短，甚至不像我在研究的代码中看到的那样。
这些评论构成了大部分文本，并提供了有关的详细信息参数和返回值包括描述性文本。

我的问题是，如果有关于如何提供所有这些信息以及从何处获取信息的惯例？这是手写还是有办法从某个地方提取它？

以下是我正在研究的代码片段：



        # 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

Answer 1

这是yard format中的文档。

✓http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md

这是手写还是有办法从某个地方提取它？

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

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

1 个答案: