Ruby: Как правильно и эффективно писать комментарии?

Question

Я просто читаю код для оболочки API Mailchimp для Ruby с именем Mailchimp-Api-Ruby. Я опубликую фрагмент ниже моего вопроса.

Больше, чем код, комментарии привлекли мое внимание. Это произошло по двум причинам:

1. Существует, по-видимому, соглашение о стиле для комментариев, особенно для методов, которые вызывают вызов внешнего api. Я знаю о соглашениях типа Ruby, таких как this one от Б.Бацова, в котором также есть раздел о комментариях. Но этот раздел довольно короткий и даже не близок к тому, что я вижу в коде, который я изучаю.
2. Комментарии составляют большую часть текста и содержат подробную информацию о параметрах и возвращаемых значениях, включая описательные тексты.

Мой вопрос в том, есть ли соглашение о том, как представить всю эту информацию и где ее получить? Это ручная работа или есть способ извлечь ее откуда-то?

Вот фрагмент кода, который я учусь:

 


     # 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

Это рукописная или есть способ извлечь его из куда-нибудь?

Это рукописный текст, так как я вряд ли могу представить, откуда его можно извлечь.