Ruby: 如何正确高效的写评论？

Question

我正在阅读 Ruby 的 Mailchimp API 包装器的代码，名为 Mailchimp-Api-Ruby。我将 post 在我的问题下方添加一个片段。

不仅仅是代码，评论引起了我的注意。发生这种情况有两个原因：

注释似乎有一种风格约定，尤其是对于调用外部 api 的方法。我知道 Ruby 样式约定，例如 B.Batsov 中的 this one，其中还有一个关于注释的部分。但这部分相当短，甚至与我在正在研究的代码中看到的内容相去甚远。
评论占文本的大部分，并提供有关的详细信息参数和 return 值，包括描述性文本。

我的问题是，是否有关于如何呈现所有这些信息以及从何处获取这些信息的约定？这是手写的还是有办法从某处提取它？

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



        # 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

Is this hand-written or is there a way to extract it from somewhere?

手写的，实在想不出从哪里提取出来的

Ruby: 如何正确高效的写评论？

Ruby: How to correctly and efficiently write comments?

ruby

api

comments