/usr/share/doc/yard-doc/doc/file.WhatsNew.html is in yard-doc 0.9.7-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 | <!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: What's New?
— YARD 0.9.7 Documentation
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
<script type="text/javascript" charset="utf-8">
pathId = "WhatsNew";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="file_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: What's New?</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'><h1>What's New in 0.8.x?</h1>
<ol>
<li><strong>Directives (new behavioural tag syntax)</strong> (0.8.0)</li>
<li><strong>Added <code>--embed-mixin(s)</code> to embed mixins into class docs</strong> (0.8.0)</li>
<li><strong>Internationalization (I18n) support for translating docs</strong> (0.8.0)</li>
<li><strong>New C parser / handlers architecture</strong> (0.8.0)</li>
<li><strong>YARD will now warn if <code>@param</code> name not in method params</strong> (0.8.0)</li>
<li><strong>Added support for <code>module_function</code> calls in Ruby code</strong> (0.8.0)</li>
<li><strong>Greatly improved tag documentation using custom template</strong> (0.8.0)</li>
<li><strong>Tags can now contain '.' for namespacing</strong> (0.8.0)</li>
<li><strong>Added "frames" links for non-framed pages for better nav</strong> (0.8.0)</li>
<li><strong>Added Gemfile support to YARD server for local gem sets</strong> (0.8.0)</li>
<li><strong>Server now displays README on index route like static docs</strong> (0.8.0)</li>
<li><strong>Added line numbers to <code>yard stats --list-undoc --compact</code></strong> (0.8.0)</li>
<li><strong>Single object db now default (multi-object db unsupported)</strong> (0.8.0)</li>
<li><strong>Added <code>--api</code> tag to generate documentation for API sets</strong> (0.8.1)</li>
<li><strong>Added <code>--non-transitive-tag</code> to disable transitive tag</strong> (0.8.3)</li>
<li><strong>Added <code>-B/--bind</code> to bind to a port in yard server</strong> (0.8.4)</li>
<li><strong>Added <code>asciidoc</code> markup type support</strong> (0.8.6)</li>
<li><strong>Added <code>yard markups</code> command to list available markup types</strong> (0.8.6)</li>
<li><strong>Added <code>yard display</code> command to display formatted objects</strong> (0.8.6)</li>
<li><strong>Added <code>--layout</code> to <code>yard display</code> command</strong> (0.8.6.1)</li>
<li><strong>Added <code>stats_options</code> for the rake task</strong> (0.8.7.6)</li>
</ol>
<h2>Directives (new behavioural tag syntax) (0.8.0)</h2>
<p class="note">
The tags <a href="file.Tags.html#macro" title="@!macro">@!macro</a>, <a href="file.Tags.html#method" title="@!method">@!method</a>, <a href="file.Tags.html#attribute" title="@!attribute">@!attribute</a>, <a href="file.Tags.html#group" title="@!group">@!group</a>,
<a href="file.Tags.html#endgroup" title="@!endgroup">@!endgroup</a>, <a href="file.Tags.html#scope" title="@!scope">@!scope</a> and <a href="file.Tags.html#visibility" title="@!visibility">@!visibility</a> have been changed
from meta-data tags to directives. This means they should now be called
with the "@!" prefix instead of "@". Note however that for <strong>
backward compatibility</strong>, the old "@macro", "@method", etc.,
syntax for all of these tags will still work and is supported.
</p>
<p class="note">
Some <strong>backwards incompatible</strong> changes were made to <a href="file.Tags.html#macro" title="@!macro">@!macro</a> syntax.
Please read this section carefully if you are using this tag.
</p>
<p>YARD 0.8.0 adds a new tag syntax called "directives" using the <code>@!</code>
prefix. These directive tags can be used to modify parser state while
processing objects, or even create new objects on the fly. A plugin
API is available similar to tags, and directives should be registered
in the <span class='object_link'><a href="YARD/Tags/Library.html" title="YARD::Tags::Library (class)">YARD::Tags::Library</a></span> class using <span class='object_link'><a href="YARD/Tags/Library.html#define_directive-class_method" title="YARD::Tags::Library.define_directive (method)">YARD::Tags::Library.define_directive</a></span>.</p>
<p>To use a directive, simply call it the same way as any tag. Tag syntax
is documented in <a href="file.Tags.html" title="Tags Overview">Tags Overview</a>.</p>
<h3>Notable features of directives</h3>
<h4>Directives do not need to be attached to object docstrings</h4>
<p>Unlike meta-data tags which apply to created objects, directives
do not need to be attached to an object in order to be used. This
means you can have free-standing comments with directives, such as:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @macro mymacro
</span><span class='comment'># A new macro, not attached to any docstring
</span>
<span class='comment'># ...other Ruby code here...
</span>
<span class='comment'># Using the macro:
</span><span class='comment'># @macro mymacro
</span><span class='kw'>def</span> <span class='id identifier rubyid_mymethod'>mymethod</span><span class='semicolon'>;</span> <span class='kw'>end</span>
</code></pre>
<p>You can do the same to define methods and attributes, as discussed
below.</p>
<h4><code>@!method</code> and <code>@!attribute</code> directives improved</h4>
<p>The method and attribute directives can now be used to create multiple
objects in a single docstring. Previously a <code>@method</code> or <code>@attribute</code>
tag would only create one method per docstring. In 0.8.0, you could
attach multiple methods to the same block of Ruby source, such as:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @!method foo(a, b, c)
</span><span class='comment'># @!method bar(x, y, z)
</span><span class='comment'># Docstring for code
</span><span class='id identifier rubyid_some_ruby_source'>some_ruby_source</span>
</code></pre>
<p>The above creates #foo and #bar and the source listing for both will
be <code>some_ruby_source</code> with "Docstring for code" as the docstring.</p>
<p>The attribute directive can take advantage of this functionality as well.
Note that these directives also do not need to be attached to a line of
code to be recognized; they can be in free-standing comments if the
methods are defined dynamically and not associated with any code.</p>
<h4>New <code>@!parse</code> directive to parse Ruby code</h4>
<p>A new <a href="file.Tags.html#parse" title="@!parse">@!parse</a> directive was added that allows a developer to have
YARD parse code that might not necessarily be parseable in its original
form. This is useful when using <code>instance_eval</code> and other dynamic
meta-programming techniques to define methods or perform functionality.
For instance, a common case of the "self.included" callback in module
to extend a module on a class might be in the form:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='kw'>self</span><span class='period'>.</span><span class='id identifier rubyid_included'>included</span><span class='lparen'>(</span><span class='id identifier rubyid_mod'>mod</span><span class='rparen'>)</span>
<span class='id identifier rubyid_mod'>mod</span><span class='period'>.</span><span class='id identifier rubyid_extend'>extend</span><span class='lparen'>(</span><span class='kw'>self</span><span class='rparen'>)</span>
<span class='kw'>end</span>
</code></pre>
<p>Unfortunately, this does not get picked up by YARD, but on the original
class, we can add:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>MyClass</span>
<span class='comment'># @!parse extend TheDynamicModule
</span> <span class='id identifier rubyid_include'>include</span> <span class='const'>TheDynamicModule</span>
<span class='kw'>end</span>
</code></pre>
<p>YARD will then parse the code <code>extend TheDynamicModule</code> as if
it were in the source file.</p>
<p>You can also use this technique to register regular methods as
attributes, if you did not define them with <code>attr_*</code> methods:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span><span class='semicolon'>;</span> <span class='ivar'>@foo</span> <span class='kw'>end</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo='>foo=</span><span class='lparen'>(</span><span class='id identifier rubyid_v'>v</span><span class='rparen'>)</span> <span class='ivar'>@foo</span> <span class='op'>=</span> <span class='id identifier rubyid_v'>v</span> <span class='kw'>end</span>
<span class='comment'># Register them as methods:
</span><span class='comment'># @!parse attr_accessor :foo
</span></code></pre>
<h3>Backward incompatible changes to <code>@!macro</code> directive</h3>
<p>Unfortunately, in order to create the new directives architecture,
some previously supported syntax in <code>@macro</code> tags are no longer supported.
Specifically, macros can no longer expand text on an entire docstring.
Instead, macros only expand the data that is indented inside of the tag
text.</p>
<p>This syntax is <strong>no longer supported</strong>:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @macro mymacro
</span><span class='comment'># Expanding text $1 $2 $3
</span><span class='id identifier rubyid_property'>property</span> <span class='symbol'>:a</span><span class='comma'>,</span> <span class='symbol'>:b</span><span class='comma'>,</span> <span class='symbol'>:c</span>
</code></pre>
<p>In 0.7.0 to 0.7.5, the above would have created a method with the docstring
"Expanding text a b c". This will not work in 0.8.0. Instead, you must
indent all the macro expansion data so that it is part of the <code>@macro</code>
tag as follows:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @!macro mymacro
</span><span class='comment'># Expanding text $1 $2 $3
</span><span class='id identifier rubyid_property'>property</span> <span class='symbol'>:a</span><span class='comma'>,</span> <span class='symbol'>:b</span><span class='comma'>,</span> <span class='symbol'>:c</span>
</code></pre>
<p>Note that we also use the recommended <code>@!macro</code> syntax, though <code>@macro</code>
is still supported.</p>
<h2>Added <code>--embed-mixin(s)</code> to embed mixins into class docs (0.8.0)</h2>
<p>Methods from mixins can now be embedded directly into the documentation
output for a class by using <code>--embed-mixin ModuleName</code>, or <code>--embed-mixins</code>
for all mixins. This enables a documentation writer to refactor methods
into modules without worrying about them showing up in separate files
in generated documentation. When mixin methods are embedded, they
show up in both the original module page and the pages of the classes
they are mixed into. A note is added to the method signature telling the
user where the method comes from.</p>
<p>The <code>--embed-mixin</code> command-line option can also take wildcard values
in order to match specific namespaces. For instance, you can embed
only mixins inside of a "Foo::Bar" namespace by doing:</p>
<pre class="code sh"><code class="sh">$ yard doc --embed-mixin "Foo::Bar::*"
</code></pre>
<h2>Internationalization (I18n) support for translating docs</h2>
<p>YARD now ships with the beginnings of internationalization support
for translating documentation into multiple languages. The
<code>yard i18n</code> command now allows you to generate ".pot" and ultimately
".po" files for translation with <a href="http://www.gnu.org/software/gettext">gettext</a>.</p>
<p>Note that this tool is a small step in the larger transition for
proper I18n support in YARD. We still have to add proper gettext
support to our templates for proper generation in multiple languages,
but this tool allows you to get started in translating your
documents. Improved I18n support will come throughout the 0.8.x series.</p>
<h2>New C parser / handlers architecture (0.8.0)</h2>
<p>The C parser was completely rewritten to take advantage of YARD's
parser and handler architecture. This means more YARD will be more robust
when parsing failures occur, tags and directives will now work consistently
across Ruby and CRuby files (<a href="file.Tags.html#group" title="@!group">@!group</a> will now work, for instance),
and developers can now write custom handlers that target CRuby source files.</p>
<h2>YARD will now warn if <code>@param</code> name not in method params (0.8.0)</h2>
<p>YARD will now give you a warning if you use a <code>@param</code> tag in your
source but give an invalid parameter name. This should catch a lot of
common documentation errors and help keep your documentation consistent.</p>
<h2>Added support for <code>module_function</code> calls in Ruby code (0.8.0)</h2>
<p>The <code>module_function</code> command in Ruby is now supported in Ruby files.
It defines two separate methods, one class and one instance method,
both having the exact same docstring, and marks the instance method
as private.</p>
<h2>Greatly improved tag documentation using custom template (0.8.0)</h2>
<p>We have completely revamped the docs/Tagsdocs/Tags.md to include documentation
for each meta-data tag and directive with at least one useful example
for each one. This was done using template customization and extension
available within YARD.</p>
<h2>Tags can now contain '.' for namespacing (0.8.0)</h2>
<p>Prior to 0.8.0, tags could only contain alphanumeric characters and
underscore. YARD now allows the '.' character in tag names, and it
is now recommended for namespacing project-specific custom tags.
YARD has its own set of custom tags that are namespaced in this
way (using the "yard.tagname" namespace). The namespace recommendation
is to use "projectname.tagname", or "projectname.component.tagname".</p>
<h2>Added "frames" links for non-framed pages for better nav (0.8.0)</h2>
<p>Frames navigation has always had a "(no frames)" link to get rid
of the frameset. YARD 0.8.0 introduces a "(frames)" link on non-framed
pages to reverse this, allowing you to navigate between framed and
frameless pages seamlessly.</p>
<h2>Added Gemfile support to YARD server for local gem sets (0.8.0)</h2>
<p>The <code>yard server</code> command now supports <code>--gemfile</code> to serve gems
from a Gemfile.lock, instead of all system-wide gems.</p>
<h2>Server now displays README on index route like static docs (0.8.0)</h2>
<p>The <code>yard server</code> command will now behave like static docs regarding
the index action for a project, listing the README file if present
before displaying the alphabetic index. Note that the route for
the alphabetic index page has now moved to the explicit '/index' action.</p>
<h2>Added line numbers to <code>yard stats --list-undoc --compact</code> (0.8.0)</h2>
<p>Line numbers are now listed in the compact listing of undocumented objects
so that they can be more easily located in the files.</p>
<h2>Single object db now default (multi-object db unsupported) (0.8.0)</h2>
<p>YARD previously would split the .yardoc db into multiple marshal files
for load-time performance reasons if it grew past a specific number of
objects. This check is now disabled, and YARD will never automatically
switch to a multi-object DB. YARD will now always use the single object
db unless explicitly set with <code>--no-single-db</code>. If YARD is taking a
long time to load your .yardoc database, you can try using this
option to split your database into multiple files, but note that this
can cause problems with certain codebases (specifically, if you
have class methods using the same name as a module/class).</p>
<h2>Added <code>--api</code> tag to generate documentation for API sets (0.8.1)</h2>
<p>You can now use <code>yardoc --api APINAME</code> to generate documentation only
for objects with the <code>@api APINAME</code> tag (or any parent namespace objects,
since this tag is transitive). Multiple <code>--api</code> switches may be used to
generate documentation for multiple APIs together. The following generates
documentation for both the "public" and "developer" APIs, also including
any objects with undefined API (via <code>--no-api</code>):</p>
<pre class="code ruby"><code class="ruby">$ yard doc --api public --api developer --no-api
</code></pre>
<p>Note that if you use <code>--api</code>, you must ensure that you also add <code>@api</code>
tags to your namespace objects (modules and classes), not just your methods.
If you do not want to do this, you can also include all objects with <em>no</em>
<code>@api</code> tag by using <code>--no-api</code> as shown above.</p>
<p>Remember that applying an <code>@api</code> tag to a class or module will apply it
to all children that do not have this tag already defined, so you can
declare an entire class public by applying it to the class itself. Note
also that these tags can be overridden by child elements if the tag is
re-applied to the individual object.</p>
<p>This feature is a simplified version of the more powerful <code>--query</code>
switch. The query to display the same API documentation as the
above example would be:</p>
<pre class="code ruby"><code class="ruby">$ yard doc --query '!@api || @api.text =~ /^(public|private)$/'
</code></pre>
<p>But note that <code>--query</code> does not work when YARD is in "safe mode"
due to security concerns, whereas <code>--api</code> works in either mode.
This enables <code>--api</code> to function on remote documentation sites like
<a href="http://rubydoc.info">rubydoc.info</a>.</p>
<h2>Added <code>--non-transitive-tag</code> to disable transitive tag (0.8.3)</h2>
<p>You can now use <code>--non-transitive-tag</code> to disable transitivity on
tags that are defined as transitive by default. For instance, in
some cases you might not want the @api tag to apply to all methods
when you define it on a class. Only the class itself has a specific
@api tag. To do this, you can mark @api as non-transitive with:</p>
<pre class="code ruby"><code class="ruby">$ yard doc --non-transitive-tag api --api some_api
</code></pre>
<p>Which will avoid classifying treating @api as a transitive tag
when parsing modules and classes.</p>
<h2>Added <code>-B/--bind</code> to bind to a port in yard server (0.8.4)</h2>
<p>You can now bind the <code>yard server</code> command to a given local port
with <code>yard server -B PORT</code> or <code>yard server --bind PORT</code>.</p>
<h2>Added <code>asciidoc</code> markup type support (0.8.6)</h2>
<p>Support for the AsciiDoc markup type is now introduced using the <code>asciidoc</code>
markup type (<code>yard doc -m asciidoc</code>). Requires the
<a href="http://rubygems.org/gems/asciidoctor">asciidoctor</a> RubyGem library to be
installed before running YARD.</p>
<h2>Added <code>yard markups</code> command to list available markup types (0.8.6)</h2>
<p>You can now list all available markup types and their respective providers by
typing <code>yard markups</code>. This list also includes the file extensions used to
auto-identify markup types for extra files and READMEs. To use a markup in
the list, call <code>yard doc</code> with <code>-m MARKUP_TYPE</code>. To select a specific markup
provider library, pass the <code>-M PROVIDER_NAME</code> option.</p>
<h2>Added <code>yard display</code> command to display formatted objects (0.8.6)</h2>
<p class="note">This feature requires the .yardoc registry to have already been
generated. To generate the registry, run <code>yard doc -n</code>.
</p>
<p>You can now display a single object (or a list of objects) in the YARD registry
using the <code>yard display OBJECT ...</code> command. For example, to display the
<code>YARD::CodeObjects</code> module as text (the way it is displayed in <code>yri</code>), type:</p>
<pre class="code ruby"><code class="ruby">$ yard display YARD::CodeObjects
</code></pre>
<p>You can also format individual objects as HTML. For example, you can format
the above object as HTML and pipe the contents into a file readable by a
web browser:</p>
<pre class="code ruby"><code class="ruby">$ yard display -f html YARD::CodeObjects > codeobjects.html
</code></pre>
<p>Custom templating options from <code>yard doc</code> can also be used, see
<code>yard display --help</code> for more options.</p>
<h2>Added <code>--layout</code> to <code>yard display</code> command (0.8.6.1)</h2>
<p>The <code>yard display</code> command now accepts <code>--layout</code> to wrap content in a layout
template. Currently the <code>layout</code> and <code>onefile</code> layout templates are supported,
though any template can be used. If no parameter is specified, the layout will
default to the <code>layout</code> template. Example usage:</p>
<pre class="code ruby"><code class="ruby">$ yard display --layout onefile -f html YARD::CodeObjects > codeobjects.html
</code></pre>
<p>The above generates a <code>codeobjects.html</code> file that is self-contained with
CSS stylesheets and JavaScript code. This is similar to calling
<code>yard doc --one-file</code> with only the YARD::CodeObjects object in the registry.</p>
<p>Note that even though this uses the onefile template, the README file will not
be auto-included the way it is with the <code>yard doc</code> command. To include the
README text at the top of the onefile template, pass the --readme switch:</p>
<pre class="code ruby"><code class="ruby">$ yard display --layout onefile -f html --readme README.md OBJECT > out.html
</code></pre>
<h1>What's New in 0.7.x?</h1>
<ol>
<li><strong>Macro support and detection of DSL methods</strong> (0.7.0)</li>
<li><strong>Inherited attributes now show in HTML output</strong> (0.7.0)</li>
<li><strong>The 'app' directory is now parsed by default</strong> (0.7.0)</li>
<li><strong>Added support for metadata (@title, @markup) in extra files/readmes</strong> (0.7.0)</li>
<li><strong>Added <code>yard list</code> command (alias for <code>yardoc --list</code>)</strong> (0.7.0)</li>
<li><strong>Added Git support in <code>yard diff</code></strong> (0.7.0)</li>
<li><strong>Added <code>{include:file:FILENAME}</code> syntax</strong> (0.7.0)</li>
<li><strong>Added <code>{render:OBJECT}</code> syntax to embed object docs in extra files</strong> (0.7.0)</li>
<li><strong>Added improved templates API for custom CSS/JS/menus</strong> (0.7.0)</li>
<li><strong>Added Ruby markup type (<code>-m ruby</code>)</strong> (0.7.0)</li>
<li><strong>Added state tracking variables to Parser/Handler architecture</strong> (0.7.0)</li>
<li><strong>Added before/after callbacks to SourceParser</strong> (0.7.0)</li>
<li><strong>Can now use <code>--yardopts FILE</code> to specify a custom yardopts file</strong> (0.7.0)</li>
<li><strong>Added new <code>-t guide</code> template for guide based docs</strong> (0.7.0)</li>
<li><strong>Github Flavoured Markdown now works out-of-box</strong> (0.7.4)</li>
<li><strong>Added <code>-m textile_strict</code> and <code>-m pre</code> markup types</strong> (0.7.4)</li>
<li><strong>Reorganized markup types 'text' and 'none'</strong> (0.7.4)</li>
<li><strong>Add support for <code>rb_define_alias</code></strong> (0.7.4)</li>
</ol>
<h2>Macro support and detection of DSL methods (0.7.0)</h2>
<p>YARD will now automatically detect class level method calls, similar to the
way it knows what an <code>attr_accessor</code> is. By simply adding documentation to
your class level declarations, YARD can automatically detect them as methods
or attributes in your class. Consider DataMapper's "property" declaration:</p>
<pre class="code ruby"><code class="ruby"><span class='kw'>class</span> <span class='const'>Post</span>
<span class='comment'># @attribute
</span> <span class='comment'># @return [String] the title of the post
</span> <span class='id identifier rubyid_property'>property</span> <span class='symbol'>:title</span><span class='comma'>,</span> <span class='const'><span class='object_link'><a href="String.html" title="String (class)">String</a></span></span>
<span class='kw'>end</span>
</code></pre>
<p>The above declaration would be created as the <code>Post#title</code>. The optional
<code>@attribute</code> tag tells YARD that the property is an "attribute", and not just
a regular method.</p>
<p>In addition to basic DSL method detection, YARD also supports macros to create
docstrings that can be copies to other objects; these macros can also be
"attached" to class level methods to create implicit documentation for macros.</p>
<p>Macros and DSL method detection are discussed in much more detail in the
<a href="file.GettingStarted.html" title="Getting Started Guide">Getting Started Guide</a>, so you should read about them there if you're
interested in this feature.</p>
<h2>Inherited attributes now show in HTML output (0.7.0)</h2>
<p>Inherited attributes will now show up in HTML documentation using the default
template in the same manner that inherited methods do.</p>
<h2>The 'app' directory is now parsed by default (0.7.0)</h2>
<p>YARD tries to follow the "It Just Works" attitude in writing developer tools,
and therefore has added <code>app/**/*.rb</code> to the default list of globs that it
searches for code in. You no longer need to create a <code>.yardopts</code> just to
list your app directory when documenting your code on rubydoc.info.
We should have done this a while ago! And don't worry, YARD still checks
lib and ext by default, too.</p>
<h2>Added support for metadata (@title, @markup) in extra files/readmes (0.7.0)</h2>
<p>Extra files (READMEs, ChangeLogs, LICENSE files, and other guides) now support
metadata tags, just like docstrings in code comments. By adding @tag values
to the top of a file (no whitespace preceding it) inside of a <code># comment</code> line,
YARD will detect and parse these tags and store it for later usage.</p>
<p>Tags can contain arbitrary data as well as arbitrary tag names, however the
tag names @title and @markup are reserved to specify the document title and
markup format respectively. The title will be used in the file list menu,
index page, as well as any linking of the file via the <code>{file:Filename}</code>
syntax. An example of a document with metadata would be:</p>
<pre class="code ruby"><code class="ruby"># @title The Best Project Ever!
# @markup rdoc
# @author Foo Bar (custom tag, does not display in templates)
= This Project Rules
== Contents
...
</code></pre>
<p>Note that previous versions of YARD recommended specifying the markup of an
extra file with the <code>#!markup</code> shebang, but the <code>@markup</code> metadata tag is now
the "best practice" for specifying the markup format of an extra file.</p>
<h2>Added <code>yard list</code> command (alias for <code>yardoc --list</code>) (0.7.0)</h2>
<p>The <code>yardoc --list</code> command is used to list objects that are parsed from
a codebase. This can be used to grep methods/classes in a codebase from the
command line. <code>yard list</code> now calls <code>yardoc --list</code> as a convenience command.</p>
<p>Note that the <code>yardoc --list</code> command may eventually be replaced by a more
feature-filled <code>yard list</code> command, so <code>yard list</code> should be used instead of
<code>yardoc --list</code> when possible.</p>
<h2>Added Git support in <code>yard diff</code> (0.7.0)</h2>
<p>The <code>yard diff</code> command can now perform object diffing on git repositories.
Provide the <code>--git</code> switch to <code>yard diff</code> with 2 commit/branches like so:</p>
<pre class="code ruby"><code class="ruby">$ yard diff --git HEAD~5 HEAD
Added objects:
YARD::Parser::SourceParser#contents
YARD::Parser::SourceParser#globals
...
</code></pre>
<h2>Added <code>{include:file:FILENAME}</code> syntax (0.7.0)</h2>
<p>You can now use the <code>{include:file:FILENAME}</code> syntax to embed the contents
of an extra file marked up in its markup format. This syntax supports embedding
Ruby source files and performing syntax highlighting on the code.</p>
<h2>Added <code>{render:OBJECT}</code> syntax to embed object docs in extra files (0.7.0)</h2>
<p>You can now use the <code>{render:Object}</code> syntax to embed the documentation
rendering of an entire object (method, class, module) inside of an extra file.
This is useful when writing non-API based guides that might require listing
a few helper methods or classes. The <a href="file.GettingStarted.html" title="Getting Started Guide">Getting Started Guide</a> discussed
this syntax in more detail (with example usage).</p>
<h2>Added improved templates API for custom CSS/JS/menus (0.7.0)</h2>
<p>Plugin & template developers can now more easily insert custom stylesheet
or JavaScript files in their customized templates, thanks to an abstraction
of the template API. This is documented in the docs/Templatesdocs/Templates.md document.
In addition to custom CSS/JS, developers can also create custom menu tabs
in both the framed and non framed version of the default theme.</p>
<h2>Added Ruby markup type (<code>-m ruby</code>) (0.7.0)</h2>
<p>The Ruby markup type (<code>-m ruby</code>) will now use syntax highlighting for all
formatting. This is probably not useful as a global switch, but can be used
on individual extra files using the metadata markup specification discussed
above.</p>
<h2>Added state tracking variables to Parser/Handler architecture (0.7.0)</h2>
<p>The parser and handler architecture now contain state variables
<span class='object_link'><a href="YARD/Handlers/Base.html#extra_state-instance_method" title="YARD::Handlers::Base#extra_state (method)">YARD::Handlers::Base#extra_state</a></span> and <span class='object_link'><a href="YARD/Handlers/Processor.html#globals-instance_method" title="YARD::Handlers::Processor#globals (method)">YARD::Handlers::Processor#globals</a></span>
to share data across handlers and the entire processing phase. <code>#extra_state</code>
provided a place to store per-file data, while <code>#globals</code> gives the developer
access to inter-file state when parsing multiple files at once.</p>
<h2>Added before/after callbacks to SourceParser (0.7.0)</h2>
<p>The <span class='object_link'><a href="YARD/Parser/SourceParser.html" title="YARD::Parser::SourceParser (class)">YARD::Parser::SourceParser</a></span> class can now register callbacks to execute
code before and after parsing of file globs, as well as before and after
parsing of individual files. This allows plugin developers to perform
setup/teardown (and set global state or update the <span class='object_link'><a href="YARD/Registry.html" title="YARD::Registry (module)">YARD::Registry</a></span>).</p>
<p>See the documentation for the following methods:</p>
<ul>
<li><span class='object_link'><a href="YARD/Parser/SourceParser.html#before_parse_list-class_method" title="YARD::Parser::SourceParser.before_parse_list (method)">YARD::Parser::SourceParser.before_parse_list</a></span></li>
<li><span class='object_link'><a href="YARD/Parser/SourceParser.html#after_parse_list-class_method" title="YARD::Parser::SourceParser.after_parse_list (method)">YARD::Parser::SourceParser.after_parse_list</a></span></li>
<li><span class='object_link'><a href="YARD/Parser/SourceParser.html#before_parse_file-class_method" title="YARD::Parser::SourceParser.before_parse_file (method)">YARD::Parser::SourceParser.before_parse_file</a></span></li>
<li><span class='object_link'><a href="YARD/Parser/SourceParser.html#after_parse_file-class_method" title="YARD::Parser::SourceParser.after_parse_file (method)">YARD::Parser::SourceParser.after_parse_file</a></span></li>
</ul>
<h2>Can now use <code>--yardopts FILE</code> to specify a custom yardopts file (0.7.0)</h2>
<p>The <code>yardoc</code> command now supports <code>--yardopts FILE</code> to specify custom .yardopts
options files. This is useful if you have multiple documentation sets, such
as a guide documentation set and an API documentation set.</p>
<h2>Added new <code>-t guide</code> template for guide based docs (0.7.0)</h2>
<p>You can now write guide style documentation using a new 'guide' template that
only generates documentation for extra files. You would use it in the form:</p>
<pre class="code ruby"><code class="ruby">yardoc -t guide - README GettingStarted FAQ TroubleShooting LICENSE
</code></pre>
<p>This creates the sections for the readme, a getting started, frequently asked
questions, trouble shooting and license page.</p>
<p>If you need to refer to class / method documentation, you can embed API documentation
using the <code>{render:Object}</code> tag discussed above.</p>
<h2>Github Flavoured Markdown now works out-of-box (0.7.4)</h2>
<p>Due to the growing popularity of Github-Flavoured-Markdown (GFM), YARD now uses
the Redcarpet library as the default Markdown formatting library with GFM fenced
code blocks enabled. This means that you can use fenced code blocks inside of
Markdown files with redcarpet installed without any extra code. Previously, users
who wanted GFM in their Markdown would have to specify <code>-m markdown -M redcarpet</code>,
but this is now the default behaviour for YARD.</p>
<p>Note that you can still specify language types in code blocks without GFM in YARD
by using the "!!!lang" prefix syntax. For example (plain means no markup):</p>
<pre class="code plain"><code class="plain">!!!plain
Some code
block here.
</code></pre>
<p>The GFM version would be:</p>
<pre class="code plain"><code class="plain">```plain
Some code
block here.
```
</code></pre>
<h2>Added <code>-m textile_strict</code> and <code>-m pre</code> markup types (0.7.4)</h2>
<p>A new "textile_strict" markup type was added which behaves exactly like "textile"
except it enables hard breaks, so newlines behave as line breaks in the HTML
(using <code><br></code> tags). This option is added for users who want the classic textile
behaviour.</p>
<h2>Reorganized markup types 'text' and 'none' (0.7.4)</h2>
<p>Due to the new pre markup type, the behaviour for text and none were slightly
reorganized to be more intuitive. The following behaviours now represent these
markup types:</p>
<ul>
<li>pre: Used to wrap text inside <code><pre></code> tags</li>
<li>text: No formatting except for hard breaks (<code><br></code>) on newlines</li>
<li>none: No formatting at all.</li>
</ul>
<p>In all cases, HTML is escaped from input. If you want no HTML escaping, use the
html markup type.</p>
<h2>Add support for <code>rb_define_alias</code> (0.7.4)</h2>
<p>CRuby code can now make use of the <code>rb_define_alias</code> function. Documentation
for aliases is not supported, however.</p>
<h1>What's New in 0.6.x?</h1>
<ol>
<li><strong>Local documentation server for RubyGems or projects (<code>yard server</code>)</strong> (0.6.0)</li>
<li><strong>Groups support for method listing</strong> (0.6.0)</li>
<li><strong>Single file template (<code>--one-file</code>) support</strong> (0.6.0)</li>
<li><strong><code>yard</code> CLI executable with pluggable commands</strong> (0.6.0)</li>
<li><strong><code>yard diff</code> command to object-diff two versions of a project</strong> (0.6.0)</li>
<li><strong>Added <code>--asset</code> option to <code>yardoc</code></strong> (0.6.0)</li>
<li><strong>New template API</strong> (0.6.0)</li>
<li><strong>HTML template now adds inline Table of Contents for extra files pages</strong> (0.6.0)</li>
<li><strong>Removed <code>--incremental</code> in favour of <code>--use-cache</code></strong> (0.6.0)</li>
<li><strong>Ad-hoc tag registration via <code>yardoc</code> CLI (<code>--tag</code>, etc.)</strong> (0.6.0)</li>
<li><strong>Added <code>--transitive-tags</code> to register transitive tags</strong> (0.6.0)</li>
<li><strong><code>yardoc</code> now displays RDoc-like statistics (<code>--no-stats</code> to hide)</strong> (0.6.0)</li>
<li><strong><code>yri</code> now works on constants</strong> (0.6.0)</li>
<li><strong>Plugins are no longer auto-loaded (added <code>--plugin</code> switch)</strong> (0.6.2)</li>
<li><strong>Added <code>YARD::Config</code> API and <code>~/.yard/config</code> configuration file</strong> (0.6.2)</li>
<li><strong>Added <code>yard config</code> command to view/edit configuration</strong> (0.6.2)</li>
<li><strong>Added <code>yard server -t</code> template path switch</strong> (0.6.2)</li>
<li><strong>Added <code>YARD::Server.register_static_path</code> for static server assets</strong> (0.6.2)</li>
<li><strong>YARD::Registry is now thread local</strong> (0.6.5)</li>
<li><strong>Support for ripper gem in Ruby 1.8.7</strong> (0.6.5)</li>
</ol>
<h2>Local documentation server for RubyGems or projects (<code>yard server</code>) (0.6.0)</h2>
<p>The new <code>yard server</code> command spawns a documentation server that can serve
either documentation for a local project or installed RubyGems. The server
will host (by default) on <a href="http://localhost:8808">http://localhost:8808</a>.</p>
<p>To serve documentation for the active project (in the current directory):</p>
<pre class="code ruby"><code class="ruby">$ yard server
</code></pre>
<p>The server can also run in "incremental" mode for local projects. In this
situation, any modified sources will immediately be updated at each request,
ensuring that the server always serve the code exactly as it is on disk.
Documenting your code in this fashion essentially gives you an efficient a
live preview without running a separate command everytime you make a change.
To serve documentation for the active project in incremental mode:</p>
<pre class="code ruby"><code class="ruby">$ yard server --reload
</code></pre>
<p><span class="note">Note that in incremental mode, objects or method groupings
cannot be removed. If you have removed objects or modified groupings, you
will need to flush the cache by deleting <code>.yardoc</code> and (optionally)
restarting the server.</span></p>
<p>The documentation server can also serve documentation for all installed gems
on your system, similar to <code>gem server</code>, but using YARD's functionality and
templates. To serve documentation for installed gems:</p>
<pre class="code ruby"><code class="ruby">$ yard server --gems
</code></pre>
<p><span class="note">Documentation for the gem need not be previously generated
at install-time. If documentation for the gem has not been generated, YARD
will do this for you on-the-fly. It is therefore possible to speed up your
gem installs by using <code>gem install GEMNAME --no-rdoc</code> without repercussion.
You can also add this switch to your <code>~/.gemrc</code> file so that you don't need
to re-type it each time. See <a href="http://stackoverflow.com/questions/1789376/how-do-i-make-no-ri-no-rdoc-the-default-for-gem-install">this link</a>
for exact instructions.</span></p>
<h2>Groups support for method listing (0.6.0)</h2>
<p>You can now organize methods in a class/module into logical separated groups.
These groups apply lexically and are listed in the order they are defined.
For instance, to define a group:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @group Rendering an Object
</span>
<span class='comment'># Documentation here
</span><span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span><span class='semicolon'>;</span> <span class='kw'>end</span>
<span class='comment'># Extra documentation...
</span><span class='kw'>def</span> <span class='id identifier rubyid_bar'>bar</span><span class='semicolon'>;</span> <span class='kw'>end</span>
<span class='comment'># @group Another Group
</span>
<span class='kw'>def</span> <span class='id identifier rubyid_aaa'>aaa</span><span class='semicolon'>;</span> <span class='kw'>end</span>
</code></pre>
<p><span class="note">Note that these <code>@group</code> and <code>@endgroup</code> declarations are
not "tags" and should always be separated with at least 1 line of whitespace
from any other documentation or code.</span></p>
<p>In the above example, "Rendering an Object" will be listed with "foo" and
"bar" above "Another Group", even though "aaa" comes before the two other
methods, alphabetically. To end a group, use <code>@endgroup</code>. It is not necessary
to end a group to start a new one, only if there is an object following the
group that should not belong in any group.</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># @group Group 1
</span>
<span class='kw'>def</span> <span class='id identifier rubyid_foo'>foo</span><span class='semicolon'>;</span> <span class='kw'>end</span>
<span class='comment'># @endgroup
</span>
<span class='comment'># This method should not be listed in any group
</span><span class='kw'>def</span> <span class='id identifier rubyid_bar'>bar</span><span class='semicolon'>;</span> <span class='kw'>end</span>
</code></pre>
<h2>Single file template (<code>--one-file</code>) support (0.6.0)</h2>
<p><code>yardoc</code> now has the <code>--one-file</code> option to generate a single-file template
for small scripts and libraries. In this case, any comments at the top of
the script file will be recognized as a README.</p>
<h2><code>yard</code> CLI executable with pluggable commands (0.6.0)</h2>
<p><span class="note">The <code>yardoc</code> and <code>yri</code> commands are not deprecated and can
continue to be used. They are shortcuts for <code>yard doc</code> and <code>yard ri</code>
respectively. However, <code>yard-graph</code> has been removed.</span></p>
<p>YARD now has a <code>yard</code> executable which combines all pre-existing and new
commands into a single pluggable command that is both easier to remember and
access. To get a list of commands, type <code>yard --help</code>.</p>
<p>If you are a plugin developer, you can create your own <code>yard</code> command by first
subclassing the <span class='object_link'><a href="YARD/CLI/Command.html" title="YARD::CLI::Command (class)">YARD::CLI::Command</a></span> class and then registering this class
with the <span class='object_link'><a href="YARD/CLI/CommandParser.html#commands-class_method" title="YARD::CLI::CommandParser.commands (method)">YARD::CLI::CommandParser.commands</a></span> list. For instance:</p>
<pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="YARD.html" title="YARD (module)">YARD</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="YARD/CLI.html" title="YARD::CLI (module)">CLI</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="YARD/CLI/CommandParser.html" title="YARD::CLI::CommandParser (class)">CommandParser</a></span></span><span class='period'>.</span><span class='id identifier rubyid_commands'><span class='object_link'><a href="YARD/CLI/CommandParser.html#commands-class_method" title="YARD::CLI::CommandParser.commands (method)">commands</a></span></span><span class='lbracket'>[</span><span class='symbol'>:my_command</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='const'>MyCommandClass</span>
</code></pre>
<p>The above line will enable the user to execute <code>yard my_command [options]</code>.</p>
<h2><code>yard diff</code> command to object-diff two versions of a project (0.6.0)</h2>
<p>One of the built-in commands that comes with the new <code>yard</code> executable is the
ability to do object-oriented diffing across multiple versions of the same
project, either by 2 versions of a gem, or 2 working copies. Just like
regular diffing tells you which lines have been added/removed in a file,
object diffing allows you to see what classes/methods/modules have been
added/removed between versions of a codebase.</p>
<p>For an overview of how to use <code>yard diff</code>, see <a href="http://gnuu.org/2010/06/26/yard-object-oriented-diffing/">YARD Object Oriented Diffing</a>.</p>
<h2><code>yard stats</code> to display statistics and undocumented objects (0.6.0)</h2>
<p>YARD now outputs the following statistics when <code>yard stats</code> is run:</p>
<pre class="code ruby"><code class="ruby">Files: 125
Modules: 35 ( 4 undocumented)
Classes: 139 ( 29 undocumented)
Constants: 53 ( 20 undocumented)
Methods: 602 ( 70 undocumented)
85.16% documented
</code></pre>
<p>Note that these statistics are based on what you have set to show in your
documentation. If you use <code>@private</code> tags and/or do not display
private/protected methods in your documentation, these will not show up as
undocumented. Therefore this metric is contextual.</p>
<p>You can also specifically list all undocumented objects (and their file
locations) with the <code>--list-undoc</code> option.</p>
<h2>Added <code>--asset</code> option to <code>yardoc</code> (0.6.0)</h2>
<p>The <code>yardoc</code> command can now take the <code>--asset</code> option to copy over
files/directories (recursively) to the output path after generating
documentation. The format of the argument is "from:to" where from is the
source path and to is the destination. For instance, YARD uses the following
syntax in the <code>.yardopts</code> file to copy over image assets from the
'docs/images' directory into the 'images' directory after generating HTML:</p>
<pre class="code ruby"><code class="ruby">--asset docs/images:images
</code></pre>
<h2>New template API (0.6.0)</h2>
<p>The new template API allows for easier insertion of sections within an
inherited template. You should no longer need to insert by index, an
error-prone process that could break when a template is updated. Instead of:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_sections'>sections</span><span class='period'>.</span><span class='id identifier rubyid_last'>last</span><span class='period'>.</span><span class='id identifier rubyid_place'>place</span><span class='lparen'>(</span><span class='symbol'>:my_section</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_before'>before</span><span class='lparen'>(</span><span class='symbol'>:another_section</span><span class='rparen'>)</span>
</code></pre>
<p>use:</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_sections'>sections</span><span class='period'>.</span><span class='id identifier rubyid_place'>place</span><span class='lparen'>(</span><span class='symbol'>:my_section</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_before_any'>before_any</span><span class='lparen'>(</span><span class='symbol'>:another_section</span><span class='rparen'>)</span>
</code></pre>
<p>You can see more in the <a href="file.Templates.html#Inserting_and_Traversing_Sections" title="Templates Architecture">Templates Architecture</a>
document.</p>
<h2>HTML template now adds inline Table of Contents for extra files pages (0.6.0)</h2>
<p>A table of contents is now generated dynamically using JavaScript for extra
file pages (such as README's, or this document). It is generated based off the
headers (h1,h2,... tags) used in the document, and can be floated to the
right or listed inline on the page.</p>
<h2>Ad-hoc tag registration via <code>yardoc</code> CLI (<code>--tag</code>, etc.) (0.6.0)</h2>
<p>Simple meta-data tags can now be added at the command-line and registered to
display in templates in a number of pre-defined ways. For instance, to create
a freeform text tag, use the following:</p>
<pre class="code ruby"><code class="ruby">--tag my_tag_name:"My Tag Title"
</code></pre>
<p>You can also create a "typed" tag (similar to <code>@return</code>), a typed named tag
(similar to <code>@param</code>) as well as various combinations. The full list of
options are listed in <code>yardoc --help</code> under the "Tag Options" section.</p>
<p>If you wish to create a tag to store data but do not wish to show this data
in the templates, use the <code>--hide-tag</code> option to hide it from generated output:</p>
<pre class="code ruby"><code class="ruby">--hide-tag my_tag_name
</code></pre>
<h2>Added <code>--transitive-tags</code> to register transitive tags (0.6.0)</h2>
<p>Transitive tags are tags that apply to all descendants of a namespace (class
or module) when documented on that namespace. For instance, the <code>@since</code> tag
is a transitive tag. Applying <code>@since</code> to a class will automatically apply
<code>@since</code> to all methods in the class. Creating a <code>@since</code> tag directly on a
method will override the inherited value.</p>
<p>You can specify transitive tags on the command-line by using this option. Note
that the tags must already exist (built-in or created with the <code>--tag</code> option)
to be specified as transitive. If you wish to do this programmatically, see
the <span class='object_link'><a href="YARD/Tags/Library.html#transitive_tags-class_method" title="YARD::Tags::Library.transitive_tags (method)">YARD::Tags::Library.transitive_tags</a></span> attribute.</p>
<h2><code>yardoc</code> now displays RDoc-like statistics (<code>--no-stats</code> to hide) (0.6.0)</h2>
<p>As seen in the <code>yard stats</code> feature overview, <code>yardoc</code> displays RDoc-like
statistics when it is run. The output is equivalent to typing <code>yard stats</code>.
To hide this output when yardoc is run, use <code>--no-stats</code>.</p>
<h2><code>yri</code> now works on constants (0.6.0)</h2>
<p>Templates have now been added for text view of constants, which displays any
documentation and the constant value.</p>
<h2>Plugins are no longer auto-loaded (added <code>--plugin</code> switch) (0.6.2)</h2>
<p>This is a backwards-incompatible change that disables plugins from automatically
loading when YARD starts up. From now on, you should manually declare which
plugins your project is using by adding <code>--plugin PLUGINNAME</code> to a <code>.yardopts</code>
file in the root of your project. You can also re-enable autoloaded plugins
by setting <code>load_plugins</code> to true in your configuration file (<code>yard config load_plugins true</code>,
see next item). You can also set <code>autoload_plugins</code> to a list of plugins
to be automatically loaded on start.</p>
<p>If you are a YARD plugin author, please make sure to inform your users of these
changes.</p>
<p>Note that <code>--plugin</code> switches passed on the commandline (not via <code>.yardopts</code>)
are parsed before commands are loaded, and therefore can add in new CLI commands.</p>
<h2>Added <code>YARD::Config</code> API and <code>~/.yard/config</code> configuration file (0.6.2)</h2>
<p>There is a new global configuration API that can be accessed programmatically
and set via the <code>~/.yard/config</code> file. The file is encoded as a YAML file,
and looks like:</p>
<pre class="code ruby"><code class="ruby">:load_plugins: false
:ignored_plugins:
- my_plugin
- my_other_plugin
:autoload_plugins:
- my_autoload_plugin
:safe_mode: false
</code></pre>
<p>You can also set configuration options via the command-line (see next item).</p>
<h2>Added <code>yard config</code> command to view/edit configuration (0.6.2)</h2>
<p>A new <code>yard config</code> command was created to view or edit the configuration
file via the commandline.</p>
<ul>
<li>To view the current configuration use <code>yard config --list</code>.</li>
<li>To view a specific item use <code>yard config ITEMNAME</code></li>
<li>To modify an item value use <code>yard config ITEMNAME VALUE</code></li>
</ul>
<h2>Added <code>yard server -t</code> template path switch (0.6.2)</h2>
<p>The <code>yard server</code> command now accepts <code>-t</code> or <code>--template-path</code> to register
a new template path for template customization.</p>
<h2>Added <code>YARD::Server.register_static_path</code> for static server assets (0.6.2)</h2>
<p>The server now supports a command to register static asset paths. If you are
extending the YARD::Server modules, make sure to register your asset paths
through this method.</p>
<h2>YARD::Registry is now thread local (0.6.5)</h2>
<p>Creating a new thread will now implicitly load a new Registry that can be used
to parse and process new code objects independently of the other threads. Note
that this means you can no longer use the Registry across threads; you must
either access the threadlocal object directly, or synchronize threads to do
the processing in the initial registry's thread.</p>
<h2>Support for ripper gem in Ruby 1.8.7 (0.6.5)</h2>
<p>YARD now supports the Ruby 1.8.7 port of the <code>ripper</code> gem to improve parsing
of source, both in terms of performance and functionality. When the <code>ripper</code>
gem is available, YARD will use the "new-style" handlers. You can take advantage
of this functionality by performing a <code>gem install ripper</code>.</p>
<h1>What's New in 0.5.x?</h1>
<ol>
<li><strong>Support for documenting native Ruby C code</strong> (0.5.0)</li>
<li><strong>Incremental parsing and output generation with <code>yardoc -c</code></strong> (0.5.0, 0.5.3)</li>
<li><strong>Improved <code>yri</code> support to perform lookups on installed Gems</strong> (0.5.0)</li>
<li><strong>Added <code>yardoc --default-return</code> and <code>yardoc --hide-void-return</code></strong> (0.5.0)</li>
<li><strong>Multiple syntax highlighting language support</strong> (0.5.0)</li>
<li><strong>New .yardoc format</strong> (0.5.0)</li>
<li><strong>Support for yard-doc-* gem packages as hosted .yardoc dbs</strong> (0.5.1)</li>
<li><strong>Support for extra search paths in <code>yri</code></strong> (0.5.1)</li>
<li><strong>Generating HTML docs now adds frames view</strong> (0.5.3)</li>
<li><strong>Tree view for class list</strong> (0.5.3)</li>
<li><strong>Ability to specify markup format of extra files</strong> (0.5.3)</li>
<li><strong>Keyboard shortcuts for default HTML template</strong> (0.5.4)</li>
</ol>
<h2>Support for documenting native Ruby C code (0.5.0)</h2>
<p>It is now possible to document native Ruby extensions with YARD with a new
C parser mostly borrowed from RDoc. This enables the ability to document
Ruby's core and stdlibs which will be hosted on <a href="http://yardoc.org/docs">http://yardoc.org/docs</a>. In
addition, the .yardoc dump for the Ruby-core classes will become available
as an installable gem for yri support (see #3).</p>
<h2>Incremental parsing and output generation with <code>yardoc -c</code> (0.5.0, 0.5.3)</h2>
<p class="note">Note: in 0.5.3 and above you must use <tt>--incremental</tt>
to incrementally generate HTML, otherwise only parsing will be done
incrementally but HTML will be generated with all objects. <tt>--incremental</tt>
implies <tt>-c</tt>, so no need to specify them both.</p>
<p>YARD now compares file checksums before parsing when using <code>yardoc -c</code>
(aka <code>yardoc --use-cache</code>) to do incremental parsing of only the files that
have changed. HTML (or other output format) generation will also only be
done on the objects that were parsed from changed files (*). This makes doing
a documentation development cycle much faster for quick HTML previews. Just
remember that when using incremental output generation, the index will not
be rebuilt and inter-file links might not hook up right, so it is best to
perform a full rebuild at the end of such previews.</p>
<p>(*) Only for versions prior to 0.5.3. For 0.5.3+, use <code>--incremental</code> for
incremental HTML output.</p>
<h2>Improved <code>yri</code> support to perform lookups on installed Gems (0.5.0)</h2>
<p>The <code>yri</code> executable can now perform lookups on gems that have been parsed
by yard. Therefore, to use this command you must first parse all gems with
YARD. To parse all gems, use the following command:</p>
<pre class="code ruby"><code class="ruby">$ sudo yardoc --build-gems
</code></pre>
<p>The above command builds a .yardoc file for all installed gems in the
respective gem directory. If you do not have write access to the gem path,
YARD will write the yardoc file to <code>~/.yard/gem_index/NAME-VERSION.yardoc</code>.</p>
<p>Note: you can also use <code>--re-build-gems</code> to force re-parsing of all gems.</p>
<p>You can now do lookups with yri:</p>
<pre class="code ruby"><code class="ruby">$ yri JSON
</code></pre>
<p>All lookups are cached to <code>~/.yard/yri_cache</code> for quicker lookups the second
time onward.</p>
<h2>Added <code>yardoc --default-return</code> and <code>yardoc --hide-void-return</code> (0.5.0)</h2>
<p>YARD defaults to displaying (Object) as the default return type of any
method that has not declared a @return tag. To customize the default
return type, you can specify:</p>
<pre class="code ruby"><code class="ruby">$ yardoc --default-return 'MyDefaultType'
</code></pre>
<p>You can also use the empty string to list no return type.</p>
<p>In addition, you can use --hide-void-return to ignore any method that
defines itself as a void type by: <code>@return [void]</code></p>
<h2>Multiple syntax highlighting language support (0.5.0)</h2>
<p>YARD now supports the ability to specify a language type for code blocks in
docstrings. Although no actual highlighting support is added for any language
but Ruby, you can add your own support by writing your own helper method:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'># Where LANGNAME is the language:
</span><span class='kw'>def</span> <span class='id identifier rubyid_html_syntax_highlight_LANGNAME'>html_syntax_highlight_LANGNAME</span><span class='lparen'>(</span><span class='id identifier rubyid_source'>source</span><span class='rparen'>)</span>
<span class='comment'># return highlighted HTML
</span><span class='kw'>end</span>
</code></pre>
<p>To use this language in code blocks, prefix the block with <code>!!!LANGNAME</code>:</p>
<pre class="code plain"><code class="plain">!!!python
def python_code(self):
return self
</code></pre>
<p>By the same token. you can now use <code>!!!plain</code> to ignore highlighting for
a specific code block.</p>
<h2>New .yardoc format (0.5.0)</h2>
<p>To make the above yri support possible, the .yardoc format was redesigned
to be a directory instead of a file. YARD can still load old .yardoc files,
but they will be automatically upgraded if re-saved. The new .yardoc format
does have a larger memory footprint, but this will hopefully be optimized
downward.</p>
<h2>Support for yard-doc-* gem packages as hosted .yardoc dbs (0.5.1)</h2>
<p>You can now install special YARD plugin gems titled yard-doc-NAME to get
packaged a .yardoc database. This will enable yri lookups or building docs
for the gem without the code.</p>
<p>One main use for this is the <code>yard-doc-core</code> package, which enabled yri
support for Ruby core classes (stdlib coming soon as <code>yard-doc-stdlib</code>).
To install it, simply:</p>
<pre class="code ruby"><code class="ruby">$ sudo gem install yard-doc-core
# now you can use:
$ yri String
</code></pre>
<p>This will by default install the 1.9.1 core library. To install a library
for a specific version of Ruby, use the <code>--version</code> switch on gem:</p>
<pre class="code ruby"><code class="ruby">$ sudo gem install --version '= 1.8.6' yard-doc-core
</code></pre>
<h2>Support for extra search paths in <code>yri</code> (0.5.1)</h2>
<p>You can now add custom paths to non-gem .yardoc files
by adding them as newline separated paths in <code>~/.yard/yri_search_paths</code>.</p>
<h2>Generating HTML docs now adds frames view (0.5.3)</h2>
<p><code>yardoc</code> will now create a <code>frames.html</code> file when generating HTML documents
which allows the user to view documentation inside frames, for those users who
still find frames beneficial.</p>
<h2>Tree view for class list (0.5.3)</h2>
<p>The class list now displays as an expandable tree view to better organized an
otherwise cluttered namespace. If you properly namespace your less important
classes (like Rails timezone classes), they will not take up space in the
class list unless the user looks for them.</p>
<h2>Ability to specify markup format of extra files (0.5.3)</h2>
<p>You can now specify the markup format of an extra file (like README) at the
top of the file with a shebang-like line:</p>
<pre class="code ruby"><code class="ruby"><span class='comment'>#!textile
</span><span class='id identifier rubyid_contents'>contents</span> <span class='id identifier rubyid_here'>here</span>
</code></pre>
<p>The above file contents will be rendered with a textile markup engine
(eg. RedCloth).</p>
<h2>Keyboard shortcuts for default HTML template (0.5.4)</h2>
<p>You can now access the "Class List", "Method List" and "File List" with the
'c', 'm' and 'f' keyboard shortcuts in the default HTML template, allowing
for keyboard-only navigation around YARD documentation.</p>
<h2>API for registering custom parsers (0.5.6)</h2>
<p>You can now register parsers for custom source languages by calling the
following method:</p>
<pre class="code ruby"><code class="ruby"><span class='const'>SourceParser</span><span class='period'>.</span><span class='id identifier rubyid_register_parser_type'>register_parser_type</span><span class='lparen'>(</span><span class='symbol'>:java</span><span class='comma'>,</span> <span class='const'>MyJavaParser</span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>java</span><span class='tstring_end'>'</span></span><span class='rparen'>)</span>
</code></pre>
<p>The parser class MyJavaParser should be a subclass of <span class='object_link'><a href="YARD/Parser/Base.html" title="YARD::Parser::Base (class)">YARD::Parser::Base</a></span>,
and the last argument is a set of extensions (string, array or regexp). You
can read more about registering parsers at the <span class='object_link'><a href="YARD/Parser/SourceParser.html" title="YARD::Parser::SourceParser (class)">YARD::Parser::SourceParser</a></span>
class documentation.</p>
<h1>What's New in 0.4.x?</h1>
<ol>
<li><strong>New templating engine and templates</strong></li>
<li><strong>yardoc <code>--query</code> argument</strong></li>
<li><strong>Greatly expanded API documentation</strong></li>
<li><strong>New plugin support</strong></li>
<li><strong>New tags (@abstract, @private)</strong></li>
<li><strong>Default rake task is now <code>rake yard</code></strong></li>
</ol>
<h2>New templating engine and templates</h2>
<p>The templates were redesigned, most notably removing the ugly frameset, adding
search to the class/method lists, simplifying the layout and making things
generally prettier. You should also notice that more tags are now visible in
the templates such as @todo, the new @abstract and @note tags and some others
that existed but were previously omitted from the generated documentation.</p>
<p>There is also a new templating engine (based on the tadpole templating library)
to allow for much more user customization. You can read about it in
<a href="file.Templates.html" title="Templates Architecture">Templates Architecture</a>.</p>
<h2>yardoc <code>--query</code> argument</h2>
<p>The yardoc command-line tool now supports queries to select which classes,
modules or methods to include in documentation based on their data or meta-data.
For instance, you can now generate documentation for your "public" API only by
adding "@api public" to each of your public API methods/classes and using
the following argument:</p>
<pre class="code ruby"><code class="ruby">--query '@api.text == "public"'
</code></pre>
<p>More information on queries is in the <a href="index.html" title="README">README</a>.</p>
<h2>Greatly expanded API documentation</h2>
<p>Last release focused on many how-to and architecture documents to explain
the design of YARD, but many of the actual API classes/methods were still
left undocumented. This release marks a focus on getting YARD's own documentation
up to par so that it can serve as an official reference on the recommended
conventions to use when documenting code.</p>
<h2>New plugin support</h2>
<p>YARD now supports loading of plugins via RubyGems. Any gem named <code>yard-*</code> or
<code>yard_*</code> will now be loaded when YARD starts up. Note that the '-' separator
is the recommended naming scheme.</p>
<p>To ignore plugins, add the gem names to <code>~/.yard/ignored_plugins</code> on separate
lines (or separated by whitespace).</p>
<h2>New tags (@abstract, @private)</h2>
<p>Two new tags were added to the list of builtin meta-tags in YARD. <code>@abstract</code>
marks a class/module/method as abstract while <code>@private</code> marks an object
as "private". The latter tag is used in situations where an object is public
due to Ruby's own visibility limitations (constants, classes and modules
can never be private) but not actually part of your public API. You should
use this tag sparingly, as it is not meant to be an equivalent to RDoc's
<code>:nodoc:</code> tag. Remember, YARD recommends documenting private objects too.
This tag exists so that you can create a query (<code>--query !@private</code>) to
ignore all of these private objects in your documentation. You can also
use the new <code>--no-private</code> switch, which is a shortcut to the aforementioned
query. You can read more about the new tags in the <a href="file.GettingStarted.html" title="Getting Started Guide">Getting Started Guide</a>
guide.</p>
<h2>Default rake task is now <code>rake yard</code></h2>
<p>Not a big change, but anyone using the default "rake yardoc" task should
update their scripts:</p>
<p><a href="http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0">http://github.com/lsegal/yard/commit/ad38a68dd73898b06bd5d0a1912b7d815878fae0</a></p>
<h1>What's New in 0.2.3.x?</h1>
<ol>
<li><strong>Full Ruby 1.9 support</strong></li>
<li><strong>New parser code and handler API for 1.9</strong></li>
<li><strong>A new <code>@overload</code> tag</strong></li>
<li><strong>Better documentation</strong></li>
<li><strong>Template changes and bug fixes</strong></li>
</ol>
<h2>Full Ruby 1.9 support</h2>
<p>YARD's development actually focuses primarily on 1.9 from the get-go, so it is
not an afterthought. All features are first implemented for compatibility with
1.9, but of course all functionality is also tested in 1.8.x. YARD 0.2.2 was
mostly compatible with 1.9, but the new release improves and extends in certain
areas where compatibility was lacking. The new release should be fully functional
in Ruby 1.9.</p>
<h2>New parser code and handler API for 1.9</h2>
<p>Using Ruby 1.9 also gives YARD the advantage of using the new <code>ripper</code> library
which was added to stdlib. The ripper parser is Ruby's official answer to
projects like ParseTree and ruby2ruby. Ripper allows access to the AST as it
is parsed by the Ruby compiler. This has some large benefits over alternative
projects:</p>
<ol>
<li>It is officially supported and maintained by the Ruby core team.</li>
<li>The AST is generated directly from the exact same code that drives the
compiler, meaning anything that compiles is guaranteed to generate the
equivalent AST.</li>
<li>It needs no hacks, gems or extra libs and works out of the box in 1.9.</li>
<li>It's <em>fast</em>.</li>
</ol>
<p>Having the AST means that developers looking to extend YARD have much better
access to the parsed code than in previous versions. The only caveat is that
this library is not back-compatible to 1.8.x. Because of this, there are
subtle changes to the handler extension API that developers use to extend YARD.
Namely, there is now a standard API for 1.9 and a "legacy" API that can run in
both 1.8.x and 1.9 if needed. A developer can still use the legacy API to write
handlers that are compatible for both 1.8.x and 1.9 in one shot, or decide to
implement the handler using both APIs. Realize that the benefit of using the new
API means 1.9 users will get a 2.5x parsing speed increase over running the legacy
handlers (this is <em>in addition to</em> the ~1.8x speed increase of using YARV over MRI).</p>
<h2>A new <code>@overload</code> tag</h2>
<p>The new <code>@overload</code> tag enables users to document methods that take multiple
parameters depending on context. This is basically equivalent to RDoc's call-seq,
but with a name that is more akin to the OOP concept of method overloading
that is actually being employed. Here's an example:</p>
<pre class="code ruby"><code class="ruby"> <span class='comment'># @overload def to_html(html, autolink = true)
</span> <span class='comment'># This docstring describes the specific overload only.
</span> <span class='comment'># @param [String] html the HTML
</span> <span class='comment'># @param [Boolean] autolink whether or not to atuomatically link
</span> <span class='comment'># URL references
</span> <span class='comment'># @overload def to_html(html, opts = {})
</span> <span class='comment'># @param [String] html the HTML
</span> <span class='comment'># @param [Hash] opts any attributes to add to the root HTML node
</span> <span class='kw'>def</span> <span class='id identifier rubyid_to_html'>to_html</span><span class='lparen'>(</span><span class='op'>*</span><span class='id identifier rubyid_args'>args</span><span class='rparen'>)</span>
<span class='comment'># split args depending on context
</span> <span class='kw'>end</span>
</code></pre>
<p>As you can see each overload takes its own nested tags (including a docstring)
as if it were its own method. This allows "virtual" overloading behaviour at
the API level to make Ruby look like overload-aware languages without caring
about the implementation details required to add the behaviour.</p>
<p>It is still recommended practice, however, to stay away from overloading when
possible and document the types of each method's real parameters. This allows
toolkits making use of YARD to get accurate type information for your methods,
for instance, allowing IDE autocompletion. There are, of course, situations
where overload just makes more sense.</p>
<h2>Better documentation</h2>
<p>The first few iterations of YARD were very much a proof of concept. Few people
were paying attention and it was really just pieced together to see what was
feasible. Now that YARD is gaining interest, there are many developers that
want to take advantage of its extensibility support to do some really cool stuff.
Considerable time was spent for this release documenting, at a high level, what
YARD can do and how it can be done. Expect this documentation to be extended and
improved in future releases.</p>
<h2>Template changes and bug fixes</h2>
<p>Of course no new release would be complete without fixing the old broken code.
Some tags existed but were not present in generated documentation. The templates
were mostly fixed to add the major omitted tags. In addition to template adjustments,
many parsing bugs were ironed out to make YARD much more stable with existing projects
(Rails, HAML, Sinatra, Ramaze, etc.).</p>
</div></div>
<div id="footer">
Generated by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.7 (ruby-2.3.3).
</div>
</div>
</body>
</html>
|