CODEWITHSUNDEEP
rubyapicomments
Flip
Flip

Reputation: 6761

Ruby: How to correctly and efficiently write comments?

I am just reading the code for a Mailchimp API wrapper for Ruby, named Mailchimp-Api-Ruby. I will post a snippet below my question.

More than the code, the comments caught my attention. This happened for two reasons:

  1. There seems to be a style convention for the comments, especially for methods which make a call to an external api. I know about Ruby style conventions like this one from B.Batsov, which also has a section about comments. But this section is rather short and not even close to what I see in the code I am studying.
  2. The comments make up most of the text and present detailed information about the parameters and return values including descriptive texts.

My question is, if there is a convention on how to present all this information and where to get it? Is this hand-written or is there a way to extract it from somewhere?

Here is a snippet of the code I am studying:



        # 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

Upvotes: 0

Views: 37

Answers (1)

Aleksei Matiushkin
Aleksei Matiushkin

Reputation: 121000

This is documentation in 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?

It is hand-written, since I hardly can imagine where it could be extracted from.

Upvotes: 2

Related Questions