【发布时间】：2016-06-25 16:03:26
【问题描述】：
我正在阅读用于 Ruby 的 Mailchimp API 包装器的代码，名为 Mailchimp-Api-Ruby。我将在我的问题下方发布一个 sn-p。
除了代码之外，cmets 引起了我的注意。发生这种情况有两个原因：
- cmets 似乎有一个样式约定，特别是对于调用外部 api 的方法。我知道 Ruby 样式约定，例如来自 B.Batsov 的 this one，其中也有一个关于 cmets 的部分。但是这部分内容很短，甚至与我在研究的代码中看到的内容都不相近。
- cmets 构成了大部分文本，并提供有关 参数和返回值，包括描述性文本。
我的问题是，是否有关于如何呈现所有这些信息以及从何处获取这些信息的约定？这是手写的还是有办法从某个地方提取出来的？
这是我正在研究的代码的 sn-p：
# 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
【问题讨论】：