rdoc.md

   1 ---
   2 title: Rdoc
   3 category: Markup
   4 layout: 2017/sheet
   5 ---
   6
   7 ### Basic RDoc format
   8
   9 ```rb
  10 # Foo.
  11 #
  12 # @example
  13 #
  14 #   y
  15 #   g
  16 #
  17 # @param [String] param_name The xx and xx.
  18 #
  19 # @see https://example.com/
  20 #
  21 # @return [true] if so
  22 ```
  23
  24 ### Hash parameters
  25
  26 ```rb
  27 # @param [Hash] opts the options to create a message with.
  28 # @option opts [String] :subject The subject
  29 # @option opts [String] :from ('nobody') From address
  30 # @option opts [String] :to Recipient email
  31 # @option opts [String] :body ('') The email's body
  32 ```
  33
  34 ### Parameter types
  35
  36 ```rb
  37 # @param (see User#initialize)
  38 # @param [OptionParser] opts the option parser object
  39 # @param [Array<String>] args the arguments passed from input. This
  40 #   array will be modified.
  41 # @param [Array<String, Symbol>] list the list of strings and symbols.
  42 # @param [Hash<Symbol, String>] a hash with symbol keys and string values
  43 #
  44 # The options parsed out of the commandline.
  45 # Default options are:
  46 #   :format => :dot
  47 ```
  48
  49 ### Exceptions
  50 ```rb
  51 # @raise [AccountBalanceError] if the account does not have
  52 #   sufficient funds to perform the transaction
  53 ```
  54
  55 ### Inline
  56
  57 ```markdown
  58 *bold*
  59 _emphasized_
  60 +code+
  61 ```
  62
  63 ```markdown
  64 {ObjectName#method optional title}
  65 {Class::CONSTANT My constant's title}
  66 {#method_inside_current_namespace}
  67 ```
  68
  69 ```markdown
  70 https://www.example.com/
  71 See Models::User@Examples
  72 {Google}[https://google.com/]
  73 ```
  74
  75 ### Skip
  76
  77 ```rb
  78 def input # :nodoc:
  79 ```
  80
  81 ```rb
  82 module MyModule # :nodoc: all
  83 ```
  84
  85 ### Definition lists
  86
  87 ```rb
  88 # == Definition lists
  89 #
  90 # list::  hi.
  91 # +foo+:: parameterized
  92 ```
  93
  94 ```rb
  95 # == Definition lists
  96 # [foo]   also
  97 # [bar]   like this
  98 ```
  99
 100 ### Return types
 101
 102 ```rb
 103 # @return [String]
 104 # @return [String, nil] the name
 105 ```
 106
 107 ### Callseq
 108
 109 ```rb
 110 # :call-seq:
 111 #   ARGF.readlines(sep=$/)     -> array
 112 #   ARGF.readlines(limit)      -> array
 113 #   ARGF.readlines(sep, limit) -> array
 114 #
 115 #   ARGF.to_a(sep=$/)     -> array
 116 #   ARGF.to_a(limit)      -> array
 117 #   ARGF.to_a(sep, limit) -> array
 118 ```
 119
 120 ### Category
 121
 122 ```rb
 123 # :category: Utilities
 124 ```
 125
 126 ### Sections
 127
 128 ```rb
 129 # :section: Expiry methods
 130 # methods relating to expiring
 131
 132 def expire!
 133 def expired?
 134 ...
 135 ```
 136
 137 ### Using tomdoc
 138
 139 ```rb
 140 # :markup: TomDoc
 141 ```
 142
 143 Place this at the beginning of the file.
 144
 145 ## Also see
 146 {: .-one-column}
 147
 148 * <https://docs.ruby-lang.org/en/2.1.0/RDoc/Markup.html>
 149 * <https://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md>
 150 * <https://rubydoc.info/gems/yard/file/docs/Tags.md>
 151 {: .-also-see}