yard 0.9.24 → 0.9.25

This diff has not been reviewed by any users.
Sign up to get free protection for your applications and to get access to all the features.
Files changed (223) hide show
  1. checksums.yaml +4 -4
  2. data/.rubocop.yml +37 -24
  3. data/CHANGELOG.md +18 -3
  4. data/README.md +96 -101
  5. data/Rakefile +2 -0
  6. data/lib/yard/cli/diff.rb +4 -1
  7. data/lib/yard/cli/server.rb +22 -13
  8. data/lib/yard/code_objects/proxy.rb +2 -1
  9. data/lib/yard/globals.rb +1 -1
  10. data/lib/yard/handlers/c/base.rb +164 -129
  11. data/lib/yard/parser/ruby/ruby_parser.rb +6 -4
  12. data/lib/yard/registry_store.rb +1 -1
  13. data/lib/yard/templates/helpers/html_helper.rb +10 -3
  14. data/lib/yard/templates/helpers/markup/rdoc_markup.rb +5 -4
  15. data/lib/yard/version.rb +1 -1
  16. data/tasks/update_error_map.rake +53 -0
  17. data/yard.gemspec +1 -1
  18. metadata +3 -207
  19. data/spec/cli/command_parser_spec.rb +0 -43
  20. data/spec/cli/command_spec.rb +0 -36
  21. data/spec/cli/config_spec.rb +0 -148
  22. data/spec/cli/diff_spec.rb +0 -254
  23. data/spec/cli/display_spec.rb +0 -30
  24. data/spec/cli/gems_spec.rb +0 -81
  25. data/spec/cli/graph_spec.rb +0 -18
  26. data/spec/cli/help_spec.rb +0 -22
  27. data/spec/cli/i18n_spec.rb +0 -107
  28. data/spec/cli/list_spec.rb +0 -8
  29. data/spec/cli/markup_types_spec.rb +0 -22
  30. data/spec/cli/server_spec.rb +0 -324
  31. data/spec/cli/stats_spec.rb +0 -96
  32. data/spec/cli/yard_on_yard_spec.rb +0 -38
  33. data/spec/cli/yardoc_spec.rb +0 -896
  34. data/spec/cli/yri_spec.rb +0 -101
  35. data/spec/code_objects/base_spec.rb +0 -485
  36. data/spec/code_objects/class_object_spec.rb +0 -226
  37. data/spec/code_objects/code_object_list_spec.rb +0 -36
  38. data/spec/code_objects/constants_spec.rb +0 -116
  39. data/spec/code_objects/extra_file_object_spec.rb +0 -161
  40. data/spec/code_objects/macro_object_spec.rb +0 -150
  41. data/spec/code_objects/method_object_spec.rb +0 -184
  42. data/spec/code_objects/module_object_spec.rb +0 -142
  43. data/spec/code_objects/namespace_mapper_spec.rb +0 -32
  44. data/spec/code_objects/namespace_object_spec.rb +0 -171
  45. data/spec/code_objects/proxy_spec.rb +0 -147
  46. data/spec/code_objects/spec_helper.rb +0 -3
  47. data/spec/config_spec.rb +0 -171
  48. data/spec/core_ext/array_spec.rb +0 -13
  49. data/spec/core_ext/file_spec.rb +0 -72
  50. data/spec/core_ext/hash_spec.rb +0 -14
  51. data/spec/core_ext/insertion_spec.rb +0 -37
  52. data/spec/core_ext/module_spec.rb +0 -9
  53. data/spec/core_ext/string_spec.rb +0 -42
  54. data/spec/core_ext/symbol_hash_spec.rb +0 -89
  55. data/spec/docstring_parser_spec.rb +0 -280
  56. data/spec/docstring_spec.rb +0 -373
  57. data/spec/handlers/alias_handler_spec.rb +0 -82
  58. data/spec/handlers/attribute_handler_spec.rb +0 -96
  59. data/spec/handlers/base_spec.rb +0 -216
  60. data/spec/handlers/c/alias_handler_spec.rb +0 -34
  61. data/spec/handlers/c/attribute_handler_spec.rb +0 -41
  62. data/spec/handlers/c/class_handler_spec.rb +0 -78
  63. data/spec/handlers/c/constant_handler_spec.rb +0 -71
  64. data/spec/handlers/c/init_handler_spec.rb +0 -48
  65. data/spec/handlers/c/method_handler_spec.rb +0 -327
  66. data/spec/handlers/c/mixin_handler_spec.rb +0 -44
  67. data/spec/handlers/c/module_handler_spec.rb +0 -71
  68. data/spec/handlers/c/override_comment_handler_spec.rb +0 -47
  69. data/spec/handlers/c/path_handler_spec.rb +0 -36
  70. data/spec/handlers/c/spec_helper.rb +0 -23
  71. data/spec/handlers/c/struct_handler_spec.rb +0 -16
  72. data/spec/handlers/class_condition_handler_spec.rb +0 -87
  73. data/spec/handlers/class_handler_spec.rb +0 -247
  74. data/spec/handlers/class_method_handler_shared_examples.rb +0 -133
  75. data/spec/handlers/class_variable_handler_spec.rb +0 -12
  76. data/spec/handlers/constant_handler_spec.rb +0 -112
  77. data/spec/handlers/decorator_handler_methods_spec.rb +0 -393
  78. data/spec/handlers/dsl_handler_spec.rb +0 -226
  79. data/spec/handlers/examples/alias_handler_001.rb.txt +0 -46
  80. data/spec/handlers/examples/attribute_handler_001.rb.txt +0 -32
  81. data/spec/handlers/examples/class_condition_handler_001.rb.txt +0 -69
  82. data/spec/handlers/examples/class_handler_001.rb.txt +0 -120
  83. data/spec/handlers/examples/class_variable_handler_001.rb.txt +0 -10
  84. data/spec/handlers/examples/constant_handler_001.rb.txt +0 -35
  85. data/spec/handlers/examples/dsl_handler_001.rb.txt +0 -156
  86. data/spec/handlers/examples/exception_handler_001.rb.txt +0 -59
  87. data/spec/handlers/examples/extend_handler_001.rb.txt +0 -19
  88. data/spec/handlers/examples/method_condition_handler_001.rb.txt +0 -10
  89. data/spec/handlers/examples/method_handler_001.rb.txt +0 -128
  90. data/spec/handlers/examples/mixin_handler_001.rb.txt +0 -40
  91. data/spec/handlers/examples/module_handler_001.rb.txt +0 -29
  92. data/spec/handlers/examples/private_constant_handler_001.rb.txt +0 -8
  93. data/spec/handlers/examples/process_handler_001.rb.txt +0 -11
  94. data/spec/handlers/examples/visibility_handler_001.rb.txt +0 -36
  95. data/spec/handlers/examples/yield_handler_001.rb.txt +0 -54
  96. data/spec/handlers/exception_handler_spec.rb +0 -49
  97. data/spec/handlers/extend_handler_spec.rb +0 -28
  98. data/spec/handlers/legacy_base_spec.rb +0 -128
  99. data/spec/handlers/method_condition_handler_spec.rb +0 -15
  100. data/spec/handlers/method_handler_spec.rb +0 -214
  101. data/spec/handlers/mixin_handler_spec.rb +0 -60
  102. data/spec/handlers/module_function_handler_spec.rb +0 -106
  103. data/spec/handlers/module_handler_spec.rb +0 -35
  104. data/spec/handlers/private_class_method_handler_spec.rb +0 -11
  105. data/spec/handlers/private_constant_handler_spec.rb +0 -25
  106. data/spec/handlers/processor_spec.rb +0 -35
  107. data/spec/handlers/public_class_method_handler_spec.rb +0 -11
  108. data/spec/handlers/ruby/base_spec.rb +0 -95
  109. data/spec/handlers/ruby/legacy/base_spec.rb +0 -84
  110. data/spec/handlers/spec_helper.rb +0 -33
  111. data/spec/handlers/visibility_handler_spec.rb +0 -44
  112. data/spec/handlers/yield_handler_spec.rb +0 -52
  113. data/spec/i18n/locale_spec.rb +0 -81
  114. data/spec/i18n/message_spec.rb +0 -52
  115. data/spec/i18n/messages_spec.rb +0 -67
  116. data/spec/i18n/pot_generator_spec.rb +0 -295
  117. data/spec/i18n/text_spec.rb +0 -184
  118. data/spec/logging_spec.rb +0 -44
  119. data/spec/options_spec.rb +0 -171
  120. data/spec/parser/base_spec.rb +0 -24
  121. data/spec/parser/c_parser_spec.rb +0 -236
  122. data/spec/parser/examples/array.c.txt +0 -6267
  123. data/spec/parser/examples/example1.rb.txt +0 -8
  124. data/spec/parser/examples/extrafile.c.txt +0 -8
  125. data/spec/parser/examples/file.c.txt +0 -28
  126. data/spec/parser/examples/multifile.c.txt +0 -22
  127. data/spec/parser/examples/namespace.cpp.txt +0 -68
  128. data/spec/parser/examples/override.c.txt +0 -424
  129. data/spec/parser/examples/parse_in_order_001.rb.txt +0 -2
  130. data/spec/parser/examples/parse_in_order_002.rb.txt +0 -2
  131. data/spec/parser/examples/tag_handler_001.rb.txt +0 -8
  132. data/spec/parser/ruby/ast_node_spec.rb +0 -33
  133. data/spec/parser/ruby/legacy/statement_list_spec.rb +0 -299
  134. data/spec/parser/ruby/legacy/token_list_spec.rb +0 -79
  135. data/spec/parser/ruby/ruby_parser_spec.rb +0 -520
  136. data/spec/parser/ruby/token_resolver_spec.rb +0 -165
  137. data/spec/parser/source_parser_spec.rb +0 -727
  138. data/spec/parser/tag_parsing_spec.rb +0 -17
  139. data/spec/rake/yardoc_task_spec.rb +0 -118
  140. data/spec/registry_resolver_spec.rb +0 -15
  141. data/spec/registry_spec.rb +0 -463
  142. data/spec/registry_store_spec.rb +0 -327
  143. data/spec/rubygems/doc_manager_spec.rb +0 -112
  144. data/spec/serializers/data/serialized_yardoc/checksums +0 -1
  145. data/spec/serializers/data/serialized_yardoc/objects/Foo.dat +0 -0
  146. data/spec/serializers/data/serialized_yardoc/objects/Foo/bar_i.dat +0 -0
  147. data/spec/serializers/data/serialized_yardoc/objects/Foo/baz_i.dat +0 -0
  148. data/spec/serializers/data/serialized_yardoc/objects/root.dat +0 -0
  149. data/spec/serializers/data/serialized_yardoc/proxy_types +0 -2
  150. data/spec/serializers/file_system_serializer_spec.rb +0 -145
  151. data/spec/serializers/spec_helper.rb +0 -2
  152. data/spec/serializers/yardoc_serializer_spec.rb +0 -90
  153. data/spec/server/adapter_spec.rb +0 -39
  154. data/spec/server/commands/base_spec.rb +0 -91
  155. data/spec/server/commands/library_command_spec.rb +0 -39
  156. data/spec/server/doc_server_helper_spec.rb +0 -72
  157. data/spec/server/doc_server_serializer_spec.rb +0 -60
  158. data/spec/server/rack_adapter_spec.rb +0 -21
  159. data/spec/server/router_spec.rb +0 -123
  160. data/spec/server/spec_helper.rb +0 -22
  161. data/spec/server/static_caching_spec.rb +0 -47
  162. data/spec/server/webrick_servlet_spec.rb +0 -20
  163. data/spec/server_spec.rb +0 -19
  164. data/spec/spec_helper.rb +0 -212
  165. data/spec/tags/default_factory_spec.rb +0 -168
  166. data/spec/tags/default_tag_spec.rb +0 -11
  167. data/spec/tags/directives_spec.rb +0 -463
  168. data/spec/tags/library_spec.rb +0 -48
  169. data/spec/tags/overload_tag_spec.rb +0 -53
  170. data/spec/tags/ref_tag_list_spec.rb +0 -53
  171. data/spec/tags/types_explainer_spec.rb +0 -203
  172. data/spec/templates/class_spec.rb +0 -45
  173. data/spec/templates/constant_spec.rb +0 -41
  174. data/spec/templates/engine_spec.rb +0 -131
  175. data/spec/templates/examples/class001.html +0 -308
  176. data/spec/templates/examples/class001.txt +0 -36
  177. data/spec/templates/examples/class002.html +0 -39
  178. data/spec/templates/examples/constant001.txt +0 -25
  179. data/spec/templates/examples/constant002.txt +0 -7
  180. data/spec/templates/examples/constant003.txt +0 -11
  181. data/spec/templates/examples/method001.html +0 -137
  182. data/spec/templates/examples/method001.txt +0 -35
  183. data/spec/templates/examples/method002.html +0 -91
  184. data/spec/templates/examples/method002.txt +0 -20
  185. data/spec/templates/examples/method003.html +0 -165
  186. data/spec/templates/examples/method003.txt +0 -45
  187. data/spec/templates/examples/method004.html +0 -48
  188. data/spec/templates/examples/method004.txt +0 -10
  189. data/spec/templates/examples/method005.html +0 -105
  190. data/spec/templates/examples/method005.txt +0 -33
  191. data/spec/templates/examples/method006.html +0 -108
  192. data/spec/templates/examples/method006.txt +0 -20
  193. data/spec/templates/examples/module001.dot +0 -33
  194. data/spec/templates/examples/module001.html +0 -833
  195. data/spec/templates/examples/module001.txt +0 -33
  196. data/spec/templates/examples/module002.html +0 -341
  197. data/spec/templates/examples/module003.html +0 -202
  198. data/spec/templates/examples/module004.html +0 -394
  199. data/spec/templates/examples/module005.html +0 -82
  200. data/spec/templates/examples/tag001.txt +0 -82
  201. data/spec/templates/helpers/base_helper_spec.rb +0 -171
  202. data/spec/templates/helpers/html_helper_spec.rb +0 -666
  203. data/spec/templates/helpers/html_syntax_highlight_helper_spec.rb +0 -65
  204. data/spec/templates/helpers/markup/rdoc_markup_spec.rb +0 -84
  205. data/spec/templates/helpers/markup_helper_spec.rb +0 -136
  206. data/spec/templates/helpers/method_helper_spec.rb +0 -107
  207. data/spec/templates/helpers/module_helper_spec.rb +0 -35
  208. data/spec/templates/helpers/shared_signature_examples.rb +0 -126
  209. data/spec/templates/helpers/text_helper_spec.rb +0 -65
  210. data/spec/templates/markup_processor_integrations/asciidoctor_spec.rb +0 -60
  211. data/spec/templates/markup_processor_integrations/integration_spec_helper.rb +0 -50
  212. data/spec/templates/markup_processor_integrations/rdoc_markdown_spec.rb +0 -48
  213. data/spec/templates/markup_processor_integrations/rdoc_spec.rb +0 -39
  214. data/spec/templates/markup_processor_integrations/redcarpet_spec.rb +0 -64
  215. data/spec/templates/markup_processor_integrations/redcloth_spec.rb +0 -64
  216. data/spec/templates/method_spec.rb +0 -118
  217. data/spec/templates/module_spec.rb +0 -203
  218. data/spec/templates/onefile_spec.rb +0 -66
  219. data/spec/templates/section_spec.rb +0 -144
  220. data/spec/templates/spec_helper.rb +0 -76
  221. data/spec/templates/tag_spec.rb +0 -52
  222. data/spec/templates/template_spec.rb +0 -410
  223. data/spec/verifier_spec.rb +0 -106
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 53bb10d04117e8e6b53dc07a0b93520b0a08b713a77588254c85dfeec52ace67
4
- data.tar.gz: 4945cd96795da8c07ef2eb571536ba0ad5f6a9a0f185717c6ba20943e5cc3153
3
+ metadata.gz: '069382132042276687f3551fe9f55d143635a028d5e4a1c5796e122a6871af8d'
4
+ data.tar.gz: f9b76a7d6051ce84375ba417a80f477961bfd2a03e9d8b9908615d7958bf96a0
5
5
  SHA512:
6
- metadata.gz: 50ee44093b616fddc463b77168111c4c5047995a83582968792c9bab6ec4ace104ccd074397e4925c7fbe5e2c2c273413c9163a00ad016a3c4a895d433b0b1d4
7
- data.tar.gz: 824c71f1724f55ccc7f4a0e98e69df583d0f553ae908ec75fe1d080b596e1bed028c12d6d422f3a9841a5b50e07394cd2059c4412a91c48efb23840977346f44
6
+ metadata.gz: a270998fd0d1efc6b41fa43c0b273935953c57cc17c95a11b7faa91476f2edeae14e481570acdaa3b3e824eaf9da9dd4bc3941b9e2cdbee76a193ac129251573
7
+ data.tar.gz: f196bef07edee0bdbca743d03db9e13f589ab9b19f5ebe7fefdee2b7fadf784b88d0c811cf8f67471fd58718247f780abaa67a7a16556729944e6f56ebc7abf0
@@ -1,13 +1,11 @@
1
1
  #inherit_from:
2
2
  # - .rubocop_todo.yml
3
3
 
4
- AllCops:
5
- TargetRubyVersion: 2.4
6
- Exclude:
7
- - 'vendor/**/*' # need to reset this apparently
8
- - 'lib/yard/parser/ruby/legacy/ruby_lex.rb' # old file, don't touch
9
4
  Metrics:
10
5
  Enabled: false
6
+ Layout/LineLength:
7
+ AutoCorrect: true
8
+ Max: 100
11
9
  Style/Semicolon:
12
10
  AllowAsExpressionSeparator: true
13
11
  Style/Documentation:
@@ -16,23 +14,21 @@ Style/ClassVars:
16
14
  Enabled: false
17
15
  Style/HashSyntax:
18
16
  EnforcedStyle: hash_rockets
19
- Style/SpaceInsideHashLiteralBraces:
17
+ Layout/SpaceInsideHashLiteralBraces:
20
18
  EnforcedStyle: no_space
21
- Style/SpaceInsideBlockBraces:
19
+ Layout/SpaceInsideBlockBraces:
22
20
  SpaceBeforeBlockParameters: false
23
- Style/MultilineMethodCallIndentation:
24
- EnforcedStyle: indented
25
21
  Style/NumericPredicate: # ruby 1.8/1.9 do not have positive?/negative?
26
22
  EnforcedStyle: comparison
27
- Style/MultilineMethodCallIndentation:
23
+ Layout/MultilineMethodCallIndentation:
28
24
  EnforcedStyle: indented
29
- Style/DotPosition:
25
+ Layout/DotPosition:
30
26
  EnforcedStyle: trailing
31
27
  Style/FormatString:
32
28
  EnforcedStyle: percent
33
- Style/IndentArray:
29
+ Layout/FirstArrayElementIndentation:
34
30
  EnforcedStyle: consistent
35
- Style/IndentHash:
31
+ Layout/FirstHashElementIndentation:
36
32
  EnforcedStyle: consistent
37
33
 
38
34
  # Disable these until we know what to do with them
@@ -40,29 +36,31 @@ Style/SafeNavigation:
40
36
  Enabled: false # not supported in 1.8...2.1
41
37
  Style/GuardClause: # does not provide much value
42
38
  Enabled: false
43
- Style/VariableNumber:
39
+ Naming/VariableNumber:
40
+ Enabled: false
41
+ Naming/AccessorMethodName: # this creates breaking changes in the API
44
42
  Enabled: false
45
- Style/AccessorMethodName: # this creates breaking changes in the API
43
+ Naming/PredicateName: # this creates breaking changes in the API
46
44
  Enabled: false
47
- Style/PredicateName: # this creates breaking changes in the API
45
+ Style/MethodMissingSuper: # this doesn't exist in 1.8/1.9
48
46
  Enabled: false
49
- Style/MethodMissing: # this doesn't exist in 1.8/1.9
47
+ Style/MissingRespondToMissing: # this doesn't exist in 1.8/1.9
50
48
  Enabled: false
51
49
  Style/Lambda: # not supported in 1.8
52
50
  Enabled: false
53
51
  Style/EachWithObject: # not supported in 1.8
54
52
  Enabled: false
55
- Style/AlignParameters: # does not work correctly with subsequent block
53
+ Layout/ParameterAlignment: # does not work correctly with subsequent block
56
54
  Enabled: false
57
- Style/AlignArray: # does not support indentation
55
+ Layout/ArrayAlignment: # does not support indentation
58
56
  Enabled: false
59
- Style/AlignHash: # does not support indentation
57
+ Layout/HashAlignment: # does not support indentation
60
58
  Enabled: false
61
59
  Style/MultilineTernaryOperator:
62
60
  Enabled: false
63
61
  Style/ClassAndModuleChildren:
64
62
  Enabled: false
65
- Style/EmptyLineBetweenDefs:
63
+ Layout/EmptyLineBetweenDefs:
66
64
  AllowAdjacentOneLineDefs: true
67
65
  Style/SingleLineMethods:
68
66
  Enabled: false
@@ -91,9 +89,24 @@ Style/GlobalVars:
91
89
  Exclude:
92
90
  - benchmarks/**/*.rb
93
91
  - spec/**/*.rb
94
- Lint/UnneededSplatExpansion:
92
+ Lint/RedundantSplatExpansion:
95
93
  Enabled: false
96
- Lint/Eval:
94
+ Security/Eval:
97
95
  Exclude:
98
96
  - benchmarks/**/*.rb
99
- - spec/**/*.rb
97
+ - spec/**/*.rb
98
+
99
+ Layout/SpaceAroundMethodCallOperator:
100
+ Enabled: false
101
+ Lint/RaiseException:
102
+ Enabled: false
103
+ Lint/StructNewOverride:
104
+ Enabled: false
105
+ Style/ExponentialNotation:
106
+ Enabled: false
107
+ Style/HashEachMethods:
108
+ Enabled: false
109
+ Style/HashTransformKeys:
110
+ Enabled: false
111
+ Style/HashTransformValues:
112
+ Enabled: false
@@ -1,5 +1,20 @@
1
1
  # master
2
2
 
3
+ # 0.9.25 - May 3rd, 2020
4
+
5
+ [0.9.25]: https://github.com/lsegal/yard/compare/v0.9.24...v0.9.25
6
+
7
+ - Fix parsing issue with conditional blocks mixed with conditional modifiers.
8
+ (#1308, #1324, #1326, #1327)
9
+ - Add table of contents IDs to redcarpet generated markdown. (#1323)
10
+ - Backport fixes for Ruby 1.9 (#1320)
11
+ - Fix parsing of checksums in yard server (#1301)
12
+ - Map Ruby C variable error names to Ruby classes (#1270, #1275)
13
+ - Fix initialization of RDocMarkup across threads (#1318)
14
+ - Remove warning for Kernel#open (#1312)
15
+ - Omit spec files in gem package (#1307)
16
+ - README updates (#1322)
17
+
3
18
  # 0.9.24 - January 8th, 2020
4
19
 
5
20
  [0.9.24]: https://github.com/lsegal/yard/compare/v0.9.23...v0.9.24
@@ -43,9 +58,9 @@
43
58
 
44
59
  - Fix parsing of stringified Symbols in Ruby source (#1256).
45
60
  - Fix path traversal vulnerability in `yard server`. This bug would allow
46
- unsanitized HTTP requests to access arbitrary files on the machine of a
47
- `yard server` host under certain conditions. Thanks to CuongMX from
48
- Viettel Cyber Security for discovering this vulnerability.
61
+ unsanitized HTTP requests to access arbitrary files on the machine of a
62
+ `yard server` host under certain conditions. Thanks to CuongMX from
63
+ Viettel Cyber Security for discovering this vulnerability.
49
64
 
50
65
  # 0.9.19 - April 2nd, 2019
51
66
 
data/README.md CHANGED
@@ -1,23 +1,22 @@
1
1
  # YARD: Yay! A Ruby Documentation Tool
2
2
 
3
- [![Homepage](http://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
4
- [![GitHub](http://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
5
- [![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
3
+ [![Homepage](https://img.shields.io/badge/home-yardoc.org-blue.svg)](http://yardoc.org)
4
+ [![GitHub](https://img.shields.io/badge/github-lsegal/yard-blue.svg)](http://github.com/lsegal/yard)
5
+ [![Documentation](https://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/yard/frames)
6
6
 
7
7
  [![Gem Version](https://badge.fury.io/rb/yard.svg)](http://github.com/lsegal/yard/releases)
8
8
  [![Build Status](https://travis-ci.org/lsegal/yard.svg?branch=master)](https://travis-ci.org/lsegal/yard)
9
9
  [![Coverage Status](https://coveralls.io/repos/github/lsegal/yard/badge.svg)](https://coveralls.io/github/lsegal/yard)
10
- [![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
10
+ [![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)
11
11
 
12
12
  ## Synopsis
13
13
 
14
- YARD is a documentation generation tool for the Ruby programming language.
15
- It enables the user to generate consistent, usable documentation that can be
14
+ YARD is a documentation generation tool for the Ruby programming language. It
15
+ enables the user to generate consistent, usable documentation that can be
16
16
  exported to a number of formats very easily, and also supports extending for
17
17
  custom Ruby constructs such as custom class level definitions. Below is a
18
18
  summary of some of YARD's notable features.
19
19
 
20
-
21
20
  ## Feature List
22
21
 
23
22
  **1. RDoc/SimpleMarkup Formatting Compatibility**: YARD is made to be compatible
@@ -25,22 +24,23 @@ with RDoc formatting. In fact, YARD does no processing on RDoc documentation
25
24
  strings, and leaves this up to the output generation tool to decide how to
26
25
  render the documentation.
27
26
 
28
- **2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other languages**:
29
- YARD uses a '@tag' style definition syntax for meta tags alongside regular code
30
- documentation. These tags should be able to happily sit side by side RDoc formatted
31
- documentation, but provide a much more consistent and usable way to describe
32
- important information about objects, such as what parameters they take and what types
33
- they are expected to be, what type a method should return, what exceptions it can
34
- raise, if it is deprecated, etc.. It also allows information to be better (and more
35
- consistently) organized during the output generation phase. You can find a list
36
- of tags in the {file:docs/Tags.md#taglist Tags.md} file.
37
-
38
- YARD also supports an optional "types" declarations for certain tags.
39
- This allows the developer to document type signatures for ruby methods and
40
- parameters in a non intrusive but helpful and consistent manner. Instead of
41
- describing this data in the body of the description, a developer may formally
42
- declare the parameter or return type(s) in a single line. Consider the
43
- following method documented with YARD formatting:
27
+ **2. Yardoc Meta-tag Formatting Like Python, Java, Objective-C and other
28
+ languages**: YARD uses a '@tag' style definition syntax for meta tags alongside
29
+ regular code documentation. These tags should be able to happily sit side by
30
+ side RDoc formatted documentation, but provide a much more consistent and usable
31
+ way to describe important information about objects, such as what parameters
32
+ they take and what types they are expected to be, what type a method should
33
+ return, what exceptions it can raise, if it is deprecated, etc.. It also allows
34
+ information to be better (and more consistently) organized during the output
35
+ generation phase. You can find a list of tags in the {file:docs/Tags.md#taglist
36
+ Tags.md} file.
37
+
38
+ YARD also supports an optional "types" declarations for certain tags. This
39
+ allows the developer to document type signatures for ruby methods and parameters
40
+ in a non intrusive but helpful and consistent manner. Instead of describing this
41
+ data in the body of the description, a developer may formally declare the
42
+ parameter or return type(s) in a single line. Consider the following method
43
+ documented with YARD formatting:
44
44
 
45
45
  ```ruby
46
46
  # Reverses the contents of a String or IO object.
@@ -53,13 +53,12 @@ def reverse(contents)
53
53
  end
54
54
  ```
55
55
 
56
- With the above @param tag, we learn that the contents parameter can either be
57
- a String or any object that responds to the 'read' method, which is more
58
- powerful than the textual description, which says it should be an IO object.
59
- This also informs the developer that they should expect to receive a String
60
- object returned by the method, and although this may be obvious for a
61
- 'reverse' method, it becomes very useful when the method name may not be as
62
- descriptive.
56
+ With the above @param tag, we learn that the contents parameter can either be a
57
+ String or any object that responds to the 'read' method, which is more powerful
58
+ than the textual description, which says it should be an IO object. This also
59
+ informs the developer that they should expect to receive a String object
60
+ returned by the method, and although this may be obvious for a 'reverse' method,
61
+ it becomes very useful when the method name may not be as descriptive.
63
62
 
64
63
  **3. Custom Constructs and Extensibility of YARD**: YARD is designed to be
65
64
  extended and customized by plugins. Take for instance the scenario where you
@@ -73,12 +72,12 @@ end
73
72
  ```
74
73
 
75
74
  This custom declaration provides dynamically generated code that is hard for a
76
- documentation tool to properly document without help from the developer. To
77
- ease the pains of manually documenting the procedure, YARD can be extended by
78
- the developer to handle the `cattr_accessor` construct and automatically create
79
- an attribute on the class with the associated documentation. This makes
80
- documenting external API's, especially dynamic ones, a lot more consistent for
81
- consumption by the users.
75
+ documentation tool to properly document without help from the developer. To ease
76
+ the pains of manually documenting the procedure, YARD can be extended by the
77
+ developer to handle the `cattr_accessor` construct and automatically create an
78
+ attribute on the class with the associated documentation. This makes documenting
79
+ external API's, especially dynamic ones, a lot more consistent for consumption
80
+ by the users.
82
81
 
83
82
  YARD is also designed for extensibility everywhere else, allowing you to add
84
83
  support for new programming languages, new data structures and even where/how
@@ -88,21 +87,20 @@ data is stored.
88
87
  dumped Namespace) which can be reloaded to do generation at a later date, or
89
88
  even auditing on code. This means that any developer can use the raw data to
90
89
  perform output generation for any custom format, such as YAML, for instance.
91
- While YARD plans to support XHTML style documentation output as well as
92
- command line (text based) and possibly XML, this may still be useful for those
93
- who would like to reap the benefits of YARD's processing in other forms, such
94
- as throwing all the documentation into a database. Another useful way of
95
- exploiting this raw data format would be to write tools that can auto generate
96
- test cases, for example, or show possible unhandled exceptions in code.
97
-
98
- **5. Local Documentation Server**: YARD can serve documentation for projects
99
- or installed gems (similar to `gem server`) with the added benefit of dynamic
90
+ While YARD plans to support XHTML style documentation output as well as command
91
+ line (text based) and possibly XML, this may still be useful for those who would
92
+ like to reap the benefits of YARD's processing in other forms, such as throwing
93
+ all the documentation into a database. Another useful way of exploiting this raw
94
+ data format would be to write tools that can auto generate test cases, for
95
+ example, or show possible unhandled exceptions in code.
96
+
97
+ **5. Local Documentation Server**: YARD can serve documentation for projects or
98
+ installed gems (similar to `gem server`) with the added benefit of dynamic
100
99
  searching, as well as live reloading. Using the live reload feature, you can
101
100
  document your code and immediately preview the results by refreshing the page;
102
101
  YARD will do all the work in re-generating the HTML. This makes writing
103
102
  documentation a much faster process.
104
103
 
105
-
106
104
  ## Installing
107
105
 
108
106
  To install YARD, use the following command:
@@ -117,14 +115,13 @@ Alternatively, if you've checked the source out directly, you can call
117
115
  `rake install` from the root project directory.
118
116
 
119
117
  **Important Note for Debian/Ubuntu users:** there's a possible chance your Ruby
120
- install lacks RDoc, which is occasionally used by YARD to convert markup to HTML.
121
- If running `which rdoc` turns up empty, install RDoc by issuing:
118
+ install lacks RDoc, which is occasionally used by YARD to convert markup to
119
+ HTML. If running `which rdoc` turns up empty, install RDoc by issuing:
122
120
 
123
121
  ```sh
124
122
  $ sudo apt-get install rdoc
125
123
  ```
126
124
 
127
-
128
125
  ## Usage
129
126
 
130
127
  There are a couple of ways to use YARD. The first is via command-line, and the
@@ -133,8 +130,8 @@ second is the Rake task.
133
130
  **1. yard Command-line Tool**
134
131
 
135
132
  YARD comes packaged with a executable named `yard` which can control the many
136
- functions of YARD, including generating documentation, graphs running the
137
- YARD server, and so on. To view a list of available YARD commands, type:
133
+ functions of YARD, including generating documentation, graphs running the YARD
134
+ server, and so on. To view a list of available YARD commands, type:
138
135
 
139
136
  ```sh
140
137
  $ yard --help
@@ -148,39 +145,36 @@ functionality.
148
145
  <span class="note">The `yardoc` executable is a shortcut for `yard doc`.</span>
149
146
 
150
147
  The most common command you will probably use is `yard doc`, or `yardoc`. You
151
- can type `yardoc --help` to see the options that YARD provides, but the
152
- easiest way to generate docs for your code is to simply type `yardoc` in your
153
- project root. This will assume your files are
154
- located in the `lib/` directory. If they are located elsewhere, you can specify
155
- paths and globs from the commandline via:
148
+ can type `yardoc --help` to see the options that YARD provides, but the easiest
149
+ way to generate docs for your code is to simply type `yardoc` in your project
150
+ root. This will assume your files are located in the `lib/` directory. If they
151
+ are located elsewhere, you can specify paths and globs from the commandline via:
156
152
 
157
153
  ```sh
158
154
  $ yardoc 'lib/**/*.rb' 'app/**/*.rb' ...etc...
159
155
  ```
160
156
 
161
- The tool will generate a `.yardoc` file which will store the cached database
162
- of your source code and documentation. If you want to re-generate your docs
163
- with another template you can simply use the `--use-cache` (or -c)
164
- option to speed up the generation process by skipping source parsing.
157
+ The tool will generate a `.yardoc` file which will store the cached database of
158
+ your source code and documentation. If you want to re-generate your docs with
159
+ another template you can simply use the `--use-cache` (or -c) option to speed up
160
+ the generation process by skipping source parsing.
165
161
 
166
162
  YARD will by default only document code in your public visibility. You can
167
- document your protected and private code by adding `--protected` or
168
- `--private` to the option switches. In addition, you can add `--no-private`
169
- to also ignore any object that has the `@private` meta-tag. This is similar
170
- to RDoc's ":nodoc:" behaviour, though the distinction is important. RDoc
171
- implies that the object with :nodoc: would not be documented, whereas
172
- YARD still recommends documenting private objects for the private API (for
173
- maintainer/developer consumption).
163
+ document your protected and private code by adding `--protected` or `--private`
164
+ to the option switches. In addition, you can add `--no-private` to also ignore
165
+ any object that has the `@private` meta-tag. This is similar to RDoc's ":nodoc:"
166
+ behaviour, though the distinction is important. RDoc implies that the object
167
+ with :nodoc: would not be documented, whereas YARD still recommends documenting
168
+ private objects for the private API (for maintainer/developer consumption).
174
169
 
175
- You can also add extra informative files (README, LICENSE) by separating
176
- the globs and the filenames with '-'.
170
+ You can also add extra informative files (README, LICENSE) by separating the
171
+ globs and the filenames with '-'.
177
172
 
178
173
  ```sh
179
174
  $ yardoc 'app/**/*.rb' - README LICENSE FAQ
180
175
  ```
181
176
 
182
- If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is
183
- used:
177
+ If no globs precede the '-' argument, the default glob (`lib/**/*.rb`) is used:
184
178
 
185
179
  ```sh
186
180
  $ yardoc - README LICENSE FAQ
@@ -188,18 +182,18 @@ $ yardoc - README LICENSE FAQ
188
182
 
189
183
  Note that the README file can be specified with its own `--readme` switch.
190
184
 
191
- You can also add a `.yardopts` file to your project directory which lists
192
- the switches separated by whitespace (newlines or space) to pass to yardoc
193
- whenever it is run. A full overview of the `.yardopts` file can be found in
185
+ You can also add a `.yardopts` file to your project directory which lists the
186
+ switches separated by whitespace (newlines or space) to pass to yardoc whenever
187
+ it is run. A full overview of the `.yardopts` file can be found in
194
188
  {YARD::CLI::Yardoc}.
195
189
 
196
190
  ### Queries
197
191
 
198
192
  The `yardoc` tool also supports a `--query` argument to only include objects
199
- that match a certain data or meta-data query. The query syntax is Ruby, though
200
- a few shortcuts are available. For instance, to document only objects that have
201
- an "@api" tag with the value "public", all of the following syntaxes would give
202
- the same result:
193
+ that match a certain data or meta-data query. The query syntax is Ruby, though a
194
+ few shortcuts are available. For instance, to document only objects that have an
195
+ "@api" tag with the value "public", all of the following syntaxes would give the
196
+ same result:
203
197
 
204
198
  ```sh
205
199
  --query '@api.text == "public"'
@@ -207,8 +201,8 @@ the same result:
207
201
  --query 'has_tag?(:api) && tag(:api).text == "public"'
208
202
  ```
209
203
 
210
- Note that the "@tag" syntax returns the first tag named "tag" on the object.
211
- To return the array of all tags named "tag", use "@@tag".
204
+ Note that the "@tag" syntax returns the first tag named "tag" on the object. To
205
+ return the array of all tags named "tag", use "@@tag".
212
206
 
213
207
  Multiple `--query` arguments are allowed in the command line parameters. The
214
208
  following two lines both check for the existence of a return and param tag:
@@ -235,12 +229,12 @@ YARD::Rake::YardocTask.new do |t|
235
229
  end
236
230
  ```
237
231
 
238
- All the settings: `files`, `options` and `stats_options` are optional. `files` will default to
239
- `lib/**/*.rb`, `options` will represents any options you might want
240
- to add and `stats_options` will pass extra options to the stats command.
241
- Again, a full list of options is available by typing `yardoc --help`
242
- in a shell. You can also override the options at the Rake command-line with the
243
- OPTS environment variable:
232
+ All the settings: `files`, `options` and `stats_options` are optional. `files`
233
+ will default to `lib/**/*.rb`, `options` will represents any options you might
234
+ want to add and `stats_options` will pass extra options to the stats command.
235
+ Again, a full list of options is available by typing `yardoc --help` in a shell.
236
+ You can also override the options at the Rake command-line with the OPTS
237
+ environment variable:
244
238
 
245
239
  ```sh
246
240
  $ rake yard OPTS='--any --extra --opts'
@@ -272,15 +266,17 @@ directory. `yri` will also cache lookups there.
272
266
 
273
267
  **4. `yard server` Documentation Server**
274
268
 
275
- The `yard server` command serves documentation for a local project or all installed
276
- RubyGems. To serve documentation for a project you are working on, simply run:
269
+ The `yard server` command serves documentation for a local project or all
270
+ installed RubyGems. To serve documentation for a project you are working on,
271
+ simply run:
277
272
 
278
273
  ```sh
279
274
  $ yard server
280
275
  ```
281
276
 
282
277
  And the project inside the current directory will be parsed (if the source has
283
- not yet been scanned by YARD) and served at [http://localhost:8808](http://localhost:8808).
278
+ not yet been scanned by YARD) and served at
279
+ [http://localhost:8808](http://localhost:8808).
284
280
 
285
281
  ### Live Reloading
286
282
 
@@ -297,10 +293,9 @@ To serve documentation for all installed gems, call:
297
293
  $ yard server --gems
298
294
  ```
299
295
 
300
- This will also automatically build documentation for any gems that have not
301
- been previously scanned. Note that in this case there will be a slight delay
302
- between the first request of a newly parsed gem.
303
-
296
+ This will also automatically build documentation for any gems that have not been
297
+ previously scanned. Note that in this case there will be a slight delay between
298
+ the first request of a newly parsed gem.
304
299
 
305
300
  **5. `yard graph` Graphviz Generator**
306
301
 
@@ -309,22 +304,22 @@ requires [Graphviz](http://www.graphviz.org) and the `dot` binary. By default
309
304
  this will generate a graph of the classes and modules in the best UML2 notation
310
305
  that Graphviz can support, but without any methods listed. With the `--full`
311
306
  option, methods and attributes will be listed. There is also a `--dependencies`
312
- option to show mixin inclusions. You can output to stdout or a file, or pipe directly
313
- to `dot`. The same public, protected and private visibility rules apply to `yard graph`.
314
- More options can be seen by typing `yard graph --help`, but here is an example:
307
+ option to show mixin inclusions. You can output to stdout or a file, or pipe
308
+ directly to `dot`. The same public, protected and private visibility rules apply
309
+ to `yard graph`. More options can be seen by typing `yard graph --help`, but
310
+ here is an example:
315
311
 
316
312
  ```sh
317
313
  $ yard graph --protected --full --dependencies
318
314
  ```
319
315
 
320
-
321
316
  ## Changelog
322
317
 
323
318
  See {file:CHANGELOG.md} for a list of changes.
324
319
 
325
320
  ## License
326
321
 
327
- YARD &copy; 2007-2018 by [Loren Segal](mailto:lsegal@soen.ca). YARD is
328
- licensed under the MIT license except for some files which come from the
329
- RDoc/Ruby distributions. Please see the {file:LICENSE} and {file:LEGAL}
330
- documents for more information.
322
+ YARD &copy; 2007-2020 by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed
323
+ under the MIT license except for some files which come from the RDoc/Ruby
324
+ distributions. Please see the {file:LICENSE} and {file:LEGAL} documents for more
325
+ information.