File: DOCUMENTING.md

package info (click to toggle)
puppet-beaker 4.21.0-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 2,184 kB
  • sloc: ruby: 19,290; sh: 32; makefile: 6
file content (191 lines) | stat: -rw-r--r-- 6,960 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191

# Contributing Documentation to Beaker

## Documents

Beyond the usual README, Beaker has an ever-growing amount of written documentation including tutorials, recipes, and other helpful information (see [docs/](docs)). Changes larger than bug fixes will usually be required to include such user-friendly documentation.

## Style

User-friendly Documentation (tutorials, how-tos, etc.) uses [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). We adopt the following conventions.

### Text

- Don't hard-wrap text blocks (including lists). There is disagreement about the ideal editor width, so don't hard-wrap text. Code blocks may be wrapped as appropriate.

### Lists

- Use `-` lists to avoid confusion with `*emphasis*`.
- Be sure to indent code blocks within list items.

### Headers

- Use Markdown Headers.
- Always place a blank line before and after headers.

### Code

- Use inline code for snippets (paths, file names, variables, partial commands, etc.)
- Use fenced blocks for code of one full line or greater
- Offset fenced blocks with whitespace before and after, except in list items.
- Mark the language of code blocks:
  ~~~
  ```console
    $ beaker --help
  ```
  ~~~
  Supported languages are documented [here](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). You will probably be using `console`, `ruby`, `puppet`, or `yaml` most of the time.
- It's nice to provide a shebang (`$`) in console examples to distinguish input from output.

## Inline

All inline/generated documentation uses [YARD](http://yardoc.org/). Below is an example usage, a quick summary of documentation expectations, and finally a short reference for those new to YARD.

They say a picture is worth a thousand words, hopefully this example will be worth more than the 154 it’s composed of:

```ruby
    #
    # @param  [Array<Host>, Host, #execute] hosts    The host(s) to act on
    # @param  [String]                      action   The action to perform
    # @param  [Hash{Symbol=>String}]        options  The options hash
    #   @option [Boolean] :noop    (false)  Set to true if you want noop mode
    #   @option [Boolean] :verbose (true)   Whether or not to log verbosely
    #
    # @yield  [result] Yields the result of action for further checking
    #   @yieldparam [Result] result A ValueObject containing action stats
    # @return [void] This method is a helper for remotely executing tasks
    #
    # @example Use this method when action must be sudone
    #     sudo_with_logging( master, ‘reboot -r’, :verbose => false )
    #
    # @example Pass this a block to perform additional checks
    #     sudo_with_logging( master, ‘apt-get update’ ) do |result|
    #       if result.exit_code == 1
    #         fail_test( ‘Apt has failed us again!’ )
    #       end
    #     end
    #
    # @see TestCase#on
    # @api dsl
    #
    def sudo_with_logging hosts, action, options = {}, &block
      return if options[:noop]

      if hosts.is_a?( Array )
        hosts.each {|h| sudo_with_logging h, action, options, &block }
      else
        result = host.execute( action, options.delete(:verbose) )
        yield result if block_given?
      end
    end
```

## Documentation Guide

Most of our documentation is done with the @tag syntax. With a few execptions tags follow this format:

    @tag [TypeOfValueInBrackets] nameOfValue Multi-word description that
      can span multiple lines, as long as lines after the first have
      greater indentation

Note: The `tag` name and the `nameOfValue` in question cannot contain spaces.

All sections should be considered mandatory, but in practice a committer can walk a contributor through the process and help ensure a high quality of documentation.  When contributing keep especially in mind that an
`@example` block will go a long way in helping understand the use case
(which also encourages use by others) and the @api tag helps to understand the scope of a Pull Request.

Please be liberal with whitespace (not trailing whitespace) and vertical alignment as it helps readability while “in code”. Default indentation is two spaces unless there are readability/vertical alignment concerns.

While the `@params`, `@returns`, etc... may seem redundant, they encourage thinking through exactly what you are doing and because of their strict format they allow a level of tooling not available in regular Ruby.

You are encouraged to run the YARD documentation server locally by:

```console
    $ rake docs
```

or

```console
    $ rake docs:bg
```

depending on whether you want the server to run in the foreground or not

Wait for the documentation to compile and then point your browser to [http://localhost:8808](http://localhost:8808).


## A Simple YARD Reference

A Hash that must be in `{:symbol => ‘string’}` format:

    @param [Hash<Symbol, String>] my_hash

This is also valid, and maybe more obvious to those used to Ruby:

    @param [Hash{Symbol=>String}]

When specifying an options hash you use `@option` to specify keys/values:

    @param [Hash{Symbol=>String}] my_opts An options hash
    @option my_opts [ClassOfValue] :key_in_question A Description
    @option my_opts [Fixnum]       :log_level       The log level to run in.
    @option my_opts [Boolean]      :turbo (true)    Who doesn’t want turbos?

This parameter takes an unordered list of Strings, Fixnums, and Floats:

    @param [Array<String, Fixnum, Float>]

This is an ordered list of String, then Fixnum:

    @param [Array<(String, Fixnum)>]

This is a parameter that needs to implement certain methods:

    @param [#[], #to_s]

This documents that a method may return any of the types listed:

    @return [String, self, nil]

This is the return statement for a method only used for side effects:

    @return [void]

If a method returns a boolean (TrueClass or FalseClass) write:

    @return [Boolean]

List possible classes that the method may raise:

    @raise [Beaker::PendingTest]

List parameter names yielded by a method:

    @yield [result, self]

And specify what kind of object is yielded:

    @yieldparam [Result] result

An `example` block contains a tag, description and then indented code:

    @example Accessing Host defaults using hash syntax
        host[‘platform’]  #=> ‘debian-6-amd64’

The `api` tag can have anything behind it, please use the following when documenting harness methods:

    @api dsl        Part of the testing dsl used within tests
    @api public     Methods third party integrations can rely on
    @api private    Methods private to the harness, not to be used externally

When deprecating a method include information on newer alternatives:

    @deprecated This method is horrible. Please use {#foo} or {#bar}.

When you want to reference other information use:

    @see ClassOrModule
    @see #other_method
    @see http://web.url.com/reference Title for the link