├── README.md └── tomdoc.md /README.md: -------------------------------------------------------------------------------- 1 | # TomDoc Specification 2 | 3 | TomDoc is a code documentation specification that helps you write precise 4 | documentation that is nice to read in plain text, yet structured enough to be 5 | automatically extracted and processed by a machine. 6 | 7 | This is the TomDoc specification text. Work on the specification itself will 8 | be done here and then transferred to http://tomdoc.org when a new version has 9 | been tagged. 10 | 11 | ## Contributing 12 | 13 | This code can be found online at http://github.com/mojombo/tomdoc 14 | 15 | If you'd like to discuss the spec or ask a question, use the GitHub Issues 16 | system. To propose a concrete change, create a Pull Request on GitHub. 17 | 18 | Development happens on the `master` branch. To see older version, view this 19 | repository at one of the tagged releases. 20 | 21 | ## About 22 | 23 | TomDoc is authored primarily by Tom Preston-Werner. 24 | -------------------------------------------------------------------------------- /tomdoc.md: -------------------------------------------------------------------------------- 1 | TomDoc for Ruby - Version 1.0.0-rc1 2 | =================================== 3 | 4 | Purpose 5 | ------- 6 | 7 | TomDoc is a code documentation specification that helps you write precise 8 | documentation that is nice to read in plain text, yet structured enough to be 9 | automatically extracted and processed by a machine. 10 | 11 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", 12 | "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be 13 | interpreted as described in RFC 2119. 14 | 15 | Table of Contents 16 | ----------------- 17 | 18 | * [Method Documentation](#method) 19 | * [The Description Section](#description) 20 | * [The Arguments Section](#arguments) 21 | * [The Yields Section](#yields) 22 | * [The Examples Section](#examples) 23 | * [The Returns/Raises Section](#returns) 24 | * [The Signature Section](#signature) 25 | * [Class/Module Documentation](#class) 26 | * [Constants Documentation](#constants) 27 | * [Special Considerations](#special) 28 | * [Constructor](#constructor) 29 | * [Attributes](#attributes) 30 | 31 | 32 | 33 | Method Documentation 34 | -------------------- 35 | 36 | A quick example will serve to best illustrate the TomDoc method documentation 37 | format: 38 | 39 | # Public: Duplicate some text an arbitrary number of times. 40 | # 41 | # text - The String to be duplicated. 42 | # count - The Integer number of times to duplicate the text. 43 | # 44 | # Examples 45 | # 46 | # multiplex('Tom', 4) 47 | # # => 'TomTomTomTom' 48 | # 49 | # Returns the duplicated String. 50 | def multiplex(text, count) 51 | text * count 52 | end 53 | 54 | TomDoc for a specific method consists of a block of single comment markers (#) 55 | that appears directly above the method. There SHOULD NOT be a blank line 56 | between the comment block and the method definition. A TomDoc method block 57 | consists of six optional sections: a description section, an arguments section, 58 | a yields section, an examples section, a returns section, and a signature 59 | section. Sections MUST appear in the order listed above. Lines that contain 60 | text MUST be separated from the comment marker by a single space. Lines that do 61 | not contain text SHOULD consist of just a comment marker (no trailing spaces). 62 | 63 | 64 | 65 | ### The Description Section 66 | 67 | The description section SHOULD be in plain sentences. Each sentence SHOULD end 68 | with a period. Good descriptions explain what the code does at a high level. 69 | Make sure to explain any unexpected behavior that the method may have, or any 70 | pitfalls that the user may experience. Paragraphs SHOULD be separated with 71 | blank lines. Code within the description section should be indented three 72 | spaces from the starting comment symbol. Lines SHOULD be wrapped at 80 73 | characters. 74 | 75 | To describe the status of a method, you SHOULD use one of several prefixes: 76 | 77 | **Public:** Indicates that the method is part of the project's public API. 78 | This annotation is designed to let developers know which methods are 79 | considered stable. You SHOULD use this to document the public API of your 80 | project. This information can then be used along with [Semantic 81 | Versioning](http://semver.org) to inform decisions on when major, minor, and 82 | patch versions should be incremented. 83 | 84 | # Public: Initialize a new Widget. 85 | 86 | **Internal:** Indicates that the method is part of the project's 87 | internal API. These are methods that are intended to be called from other 88 | classes within the project but not intended for public consumption. For 89 | example: 90 | 91 | # Internal: Normalize the filename. 92 | 93 | **Deprecated:** Indicates that the method is deprecated and will be removed 94 | in a future version. You SHOULD use this to document methods that were Public 95 | but will be removed at the next major version. 96 | 97 | # Deprecated: Resize an object to the given dimensions. 98 | 99 | An example description that includes all of these elements might look 100 | something like the following. 101 | 102 | # Public: Format some data with the given format. Possible format 103 | # identifiers include: 104 | # 105 | # %i - Output the Integer i. 106 | # %f.n - Output a Float f with n decimal places rounded. 107 | # 108 | # The format String may include any text. To escape a percent sign, prefix 109 | # it with a backslash: 110 | # 111 | # "The sale price was %f.n\% off retail." 112 | 113 | 114 | 115 | ### The Arguments Section 116 | 117 | The arguments section consists of a list of arguments. Each list item MUST be 118 | comprised of the name of the argument, a dash, and an explanation of the 119 | argument in plain sentences. The expected type (or types) of each argument 120 | SHOULD be clearly indicated in the explanation. When you specify a type, use 121 | the proper classname of the type (for instance, use 'String' instead of 122 | 'string' to refer to a String type). If the argument has other constraints 123 | (e.g. duck-typed method requirements), simply state those requirements. The 124 | dashes following each argument name SHOULD be lined up in a single column. 125 | Lines SHOULD be wrapped at 80 columns. Wrapped lines MUST be indented, as a 126 | block, under the parent line by at least two spaces, but SHOULD be indented 127 | to match the indentation of the explanation. For example: 128 | 129 | # element - The Symbol representation of the element. The Symbol should 130 | # contain only lowercase ASCII alpha characters. 131 | 132 | An argument that is String-like might look like this: 133 | 134 | # actor - An object that responds to to_s. Represents the actor that 135 | # will be output in the log. 136 | 137 | All arguments are assumed to be required. If an argument is optional, you MUST 138 | specify the default value: 139 | 140 | # host - The String hostname to bind (default: '0.0.0.0'). 141 | 142 | For hash arguments, you SHOULD enumerate each valid option in a way similar 143 | to how normal arguments are defined: 144 | 145 | # options - The Hash options used to refine the selection (default: {}): 146 | # :color - The String color to restrict by (optional). 147 | # :weight - The Float weight to restrict by. The weight should 148 | # be specified in grams (optional). 149 | 150 | Ruby allows for some interesting argument capabilities. In those cases, try 151 | to explain what's going on as best as possible. Examples are a good way to 152 | demonstrate how methods should be invoked. For example: 153 | 154 | # Print a log line to STDOUT. You can customize the output by specifying 155 | # a block. 156 | # 157 | # msgs - Zero or more String messages that will be printed to the log 158 | # separated by spaces. 159 | # block - An optional block that can be used to customize the date format. 160 | # If it is present, it will be sent a Time object representing 161 | # the current time. Your block should return a String version of 162 | # the time, formatted however you please. 163 | # 164 | # Examples 165 | # 166 | # log("An error occurred.") 167 | # 168 | # log("No such file", "/var/log/server.log") do |time| 169 | # time.strftime("%Y-%m-%d %H:%M:%S") 170 | # end 171 | # 172 | # Returns nothing. 173 | def log(*msgs, &block) 174 | ... 175 | end 176 | 177 | 178 | 179 | ### The Yields Section 180 | 181 | The yields section is used to specify what is sent to the implicitly given 182 | block. The section MUST start with the word "Yields" and SHOULD contain a 183 | description and type of the yielded object. For example: 184 | 185 | # Yields the Integer index of the iteration. 186 | 187 | Lines SHOULD be wrapped at 80 columns. Wrapped lines MUST be indented, as a 188 | block, under the parent line by at least two spaces. 189 | 190 | 191 | ### The Examples Section 192 | 193 | The examples section MUST start with the word "Examples" on a line by 194 | itself. The next line SHOULD be blank. The following lines SHOULD be indented 195 | by two spaces (three spaces from the initial comment marker) and contain code 196 | that shows how to call the method and OPTIONAL examples of what it 197 | returns. Everything under the "Examples" line is considered code, so 198 | you SHOULD comment out lines that show return values. For example: 199 | 200 | # Examples 201 | # 202 | # multiplex('x', 4) 203 | # # => 'xxxx' 204 | # 205 | # multiplex('apple', 2) 206 | # # => 'appleapple' 207 | 208 | 209 | 210 | ### The Returns/Raises Section 211 | 212 | The returns section should explain in plain sentences what is returned from 213 | the method. The line MUST begin with "Returns". If only a single thing is 214 | returned, state the nature and type of the value. For example: 215 | 216 | # Returns the duplicated String. 217 | 218 | If several different types may be returned, list all of them. For example: 219 | 220 | # Returns the given element Symbol or nil if none was found. 221 | 222 | If the return value of the method is not intended to be used, then you should 223 | simply state: 224 | 225 | # Returns nothing. 226 | 227 | If the method raises exceptions that the caller may be interested in, add 228 | additional lines that explain each exception and under what conditions it may 229 | be encountered. The lines MUST begin with "Raises". For example: 230 | 231 | # Returns nothing. 232 | # Raises Errno::ENOENT if the file cannot be found. 233 | # Raises Errno::EACCES if the file cannot be accessed. 234 | 235 | Lines SHOULD be wrapped at 80 columns. Wrapped lines MUST be indented, as a 236 | block, under the parent line by at least two spaces. For example: 237 | 238 | # Returns the atomic mass of the element as a Float. The value is in 239 | # unified atomic mass units. 240 | 241 | 242 | 243 | ### The Signature Section 244 | 245 | The signature section allows you to specify the nature of methods that are 246 | dynamically created at runtime. 247 | 248 | The section MUST start with the word "Signature" on a line by itself. The next 249 | line SHOULD be blank. The following lines SHOULD be indented by two spaces 250 | (three spaces from the initial comment marker) and contain special code that 251 | shows the method signature(s). For complex dynamic signatures, you SHOULD name 252 | and demarcate signature variables with `<>` for required parts and `[]` for 253 | optional parts. Use `...` for repeating elements. If there are dynamic 254 | elements to the signature, document them in the same way as the Arguments 255 | section, but leave out any type declarations. Documentation for metaprogrammed 256 | methods may exist independently of any actual code, or may appear above the 257 | code that creates the methods. Use your best judgment. 258 | 259 | # Signature 260 | # 261 | # find_by_[_and_...](args) 262 | # 263 | # field - A field name. 264 | 265 | Because metaprogrammed methods may be difficult to decipher, it's best to 266 | include an examples section to demonstrate proper usage. For example: 267 | 268 | # Public: Find Records by a specific field name and value. This method 269 | # will be available for each field defined on the record. 270 | # 271 | # args - The value or Array of values of the field(s) to find by. 272 | # 273 | # Examples 274 | # 275 | # find_by_name_and_email("Tom", "tom@mojombo.com") 276 | # 277 | # Returns an Array of matching Records. 278 | # 279 | # Signature 280 | # 281 | # find_by_[_and_...](args) 282 | # 283 | # field - A field name. 284 | 285 | 286 | 287 | Class/Module Documentation 288 | -------------------------- 289 | 290 | TomDoc for classes and modules follows the same form as Method Documentation 291 | but only contains the Description and Examples sections. 292 | 293 | # Public: Various methods useful for performing mathematical operations. 294 | # All methods are module methods and should be called on the Math module. 295 | # 296 | # Examples 297 | # 298 | # Math.square_root(9) 299 | # # => 3 300 | module Math 301 | ... 302 | end 303 | 304 | Just like methods, classes may be marked as Public, Internal, or Deprecated 305 | depending on their intended use. 306 | 307 | 308 | 309 | Constants Documentation 310 | ----------------------- 311 | 312 | Constants should be documented with freeform comments. The type of the 313 | constant and any important constraints should be stated. 314 | 315 | # Public: Integer number of seconds to wait before connection timeout. 316 | CONNECTION_TIMEOUT = 60 317 | 318 | Just like methods, constants may be marked as Public, Internal, or Deprecated 319 | depending on their intended use. 320 | 321 | 322 | 323 | Special Considerations 324 | ---------------------- 325 | 326 | 327 | ### Constructor 328 | 329 | A Ruby class's `initialize` method does not have a significant return value. 330 | You MAY exclude the returns section. A larger description of the purpose of 331 | this class should be done at the Class level. 332 | 333 | # Public: Initialize a Widget. 334 | # 335 | # name - A String naming the widget. 336 | def initialize(name) 337 | ... 338 | end 339 | 340 | 341 | ### Attributes 342 | 343 | Ruby's built in `attr_reader`, `attr_writer`, and `attr_accessor` require a 344 | bit more consideration. With TomDoc you SHOULD document each of these method 345 | generators separately. Because each part of a method documentation section is 346 | optional, you can write concise yet unambiguous docs. 347 | 348 | Here is an example TomDoc for `attr_reader`. 349 | 350 | # Public: Returns the String name of the user. 351 | attr_reader :name 352 | 353 | Here is an example TomDoc for `attr_writer`. 354 | 355 | # Public: Sets the String name of the user. 356 | attr_writer :name 357 | 358 | For `attr_accessor` you can use an overloaded shorthand that documents the 359 | getter and setter simultaneously: 360 | 361 | # Public: Gets/Sets the String name of the user. 362 | attr_accessor :name 363 | --------------------------------------------------------------------------------