manager 0.1.0 → 0.1.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHART.html +71 -67
- data/MANUAL.html +64 -60
- data/index.html +1252 -0
- data/manager.gemspec +3 -3
- data/spec/documentation +16 -2
- metadata +4 -3
data/MANUAL.html
CHANGED
|
@@ -119,7 +119,11 @@ end</span>
|
|
|
119
119
|
...
|
|
120
120
|
</pre></div>
|
|
121
121
|
</div>
|
|
122
|
-
<div class="p">After running Manager, we can see that the warning is gone from <code class="inline">CHART.html</code>, and for <code class="inline">MANUAL.html</code>, by clicking the header “Array#same_counts”, we can see that we now have documentation for the user:</div><figure><img alt="Simple example step 8" src="spec/tutorial_8.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 8. Simple example step 8</figcaption></figure><div class="p">For more examples, please see the spec files of the following gems: manager, dom, pretty_debug, compact_time, and the spec files under the directory <code class="inline">manager/examples</code>.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature5">2.2. Release Notes</h3><div class="feature-contents"><div class="user-item"><div class="p">Manager follows semantic versioning, i.e., the first number section of a version (major) corresponds to backwards incompatible API changes, the second number (minor) describes backwards compatible API changes, such as new functionality/features, and the third number (teeny) describes implementation level detail changes, such as small bug fixes.</div><ul><li>0.0.0<ul><li>Initial release.</li></ul></li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature6">3. Viewing The Files</h2><div class="feature-contents"><div class="user-item"><div class="p">Manager generates two HTML format files: a <span class="italic">user's manual</span> and a <span class="italic">developer's chart</span>. They are to be viewed on a web browser.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature7">3.1. User's Manual</h3><div class="feature-contents"><div class="user-item"><div class="p">User's manual includes <span class="italic">documentation</span> about described or implemented modules and features. It is intended to be read by the users of the software.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature8">3.1.1. Main Information</h4><div class="feature-contents"><div class="user-item"><div class="p">The <span class="italic">main information</span> is displayed in three levels:</div><ul><li><span class="italic">Modules</span> (including classes)</li><li><span class="italic">Features</span> (i.e., constants, singleton methods, instance methods, see <a href="#feature35">5.2.1. Feature</a>) and <span class="italic">section headers</span> (see <a href="#feature37">5.2.3. Section Header</a>)</li><li><span class="italic">Items</span> (contents)</li></ul><div class="p">Features described in the spec as well as features implemented within the listed files (see <a href="#feature31">5.1. Reference to Program Code</a>) will be displayed by modules. Features in the spec file will be placed first and in the order they are described in the spec. However, if the module bodies of a single module (which include feature descriptions) are scattered across multiple locations in the spec file, then they are merged together in the first location. Features implemented but not described in the spec will follow the described ones within their owner modules. They will be described with their original name in case of an alias method.</div><div class="p">Modules, features, and description sections are clickable unless their content is empty. Each one toggles elements that are more detailed than itself between hidden/displayed states. Each feature has a <span class="italic">visibility</span> tag (valued “<span class="italic">Unimplemented</span>”, “<span class="italic">protected</span>”, “<span class="italic">private</span>”, or “<span class="italic">public</span>”) and a numbered <span class="italic">type</span> tag (distinguished by “<span class="italic">Constant</span>”, “<span class="italic">Singleton method</span>”, or “<span class="italic">Instance method</span>”) except for constants that are modules.</div><div class="p">Modules (including classes) within the name space of a module other than <code class="inline">Object</code> are only displayed under the (constant) feature section with a link to where they are displayed as an independent module section. The <code class="inline">Object</code> class is displayed only if it has a feature described in the spec file or if a non-module feature of <code class="inline">Object</code> is implemented in the program code.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature9">3.1.2. Top Bar</h4><div class="feature-contents"><div class="user-item"><div class="p">At the top of the user's manual is the <span class="italic">top bar</span>, which has buttons and information to help users navigate through the file.</div><ul><li>“Modules”, “Features”, and “Full” buttons: Reset the level of detail to be displayed. “Module” button only displays the module names. “Feature” button displays up to the inventory of features as well as the headers of description sections. “Full” button displays to the full detail. Features and items can be further hidden/displayed independently or in groups by other buttons, as to be explained below; the three buttons are only responsible for the level of detail right after they are clicked.</li><li>Visibility buttons: Each button toggles between showing/hiding states of the features with the corresponding visibility. The digits beside each button represent the number of features with the visibility, and remain constant even if any of them become hidden. Buttons with numbers are omitted if the number of features is zero.</li><li>Type buttons: Each button toggles between showing/hiding states of the features of the corresponding type. The digits beside each button represent the number of features of the type, and remain constant even if any of them become hidden. Buttons with numbers are omitted if the number of features is zero.</li></ul><div class="p">The <span class="italic">left/right arrows</span> on the right of a group of buttons allow navigation through features. The numerator on the right side describes the position that was last navigated using the arrow buttons (or “1” by default). If the last navigation was done using the associated arrow buttons, then the number is displayed with emphasis. The denominator describes the number of displayed (i.e. not hidden) features. The number following the plus sign tells the user how many features they are implicitly skipping during navigation; it indicates the number of features hidden for reasons other than any property in the group being hidden. For example, the following situation:</div><figure><img alt="Navigation" src="spec/navigation.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 9. Navigation</figcaption></figure><div class="p">shows that the arrow keys next to the “Unimplemented”/“protected”/“private”/“public” group were the ones last clicked for navigation, and that the current scroll position points to the third feature among the 140 visible ones (features that are not private and not constant) unless the user has further scrolled without using any navigation buttons. As the sum of 11 (Unimplemented), 10 (protected), and 126 (public) is 147, 147 features would be expected to be displayed if nothing but private features were hidden. However, the features are hidden not only because they are private. Since constants are hidden, Unimplemented/protected/public features that are constants are hidden. The number seven after the plus sign in the first group indicates this amount. Similarly, 58 is the number of singleton/instance methods hidden because they are private.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature10">3.2. Developer's Chart</h3><div class="feature-contents"><div class="user-item"><div class="p">The contents of the developer's chart is a superset of that of the user's manual. It includes annotations, test reports, and warnings. It is intended to be utilized by the developers of the software.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature11">3.2.1. Left Panel</h4><div class="feature-contents"><div class="user-item"><div class="p">“Gem Spec” displays information given in a gem spec file if the object of Manager is a gem, and a <a href="#feature150"><code class="inline"><<::#gemspec</code></a> command is called in the spec (see below, <a href="#feature31">5.1. Reference to Program Code</a>).</div><div class="p">The <span class="italic">base directory</span> is the directory in which the spec file resides. Throughout Manager, file names are displayed either as a path relative to the base directory or as an absolute path, whichever is shorter.</div><div class="p">The “Files” table lists information about the relevant files.</div><ul><li>“Category”: Files are classified into the following.<ul><li>“Depended”: Pieces of software that are loaded during Manager run, but are neither the subject nor the object of documentation or test. In particular, the Ruby implementation that is used to run Manager, and any gems that are loaded.</li><li>“Specification”: The subject of description/tests. Also called <span class="italic">spec</span> in this manual/chart.</li><li>“Program”: Files that are the object of analysis/tests. They are described with the percentage of the number of lines covered in tests against the number of all lines in the file.</li></ul></li><li>“Version”: Version is described by the version number for depended files and by the last modified time for specification and program code files. Among the last modified times, the latest one is displayed with emphasis. This may give a hint on which file has mainly undergone modification right before the Manager was run, so that the developer can focus on reading the relevant contents.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature12">3.2.2. Main Information</h4><div class="feature-contents"><div class="user-item"><div class="p">Features in the developer's chart, unlike those in the user's manual, may be tagged by one of the followings that describe <span class="italic">documentation status</span>. They are exclusive (i.e. no feature may be tagged by more than one of them), and are not complementary (i.e. a feature may be tagged by none of them). Among them, “Undocumented” and “Misplaced” are warnings, and “hidden” or “moved” indicate markings in the spec file (see <a href="#feature35">5.2.1. Feature</a>).</div><ul><li>“Undocumented”: The feature is implemented in the program code, but is not described in the spec file.</li><li>“hidden”: The feature is marked in the spec file as to be hidden in the user's manual. This is intended to be used for features that are internal implementations, and are not meant to be public API.</li><li>“Misplaced”: The feature is under one or more of the following three occasions. This tag is suppressed when the feature is marked as “moved”.<ul><li>The feature (method) is implemented within a file that is not listed (see <a href="#feature31">5.1. Reference to Program Code</a> on how to list a feature).</li><li>The feature is implemented on an ancestor module rather than in the module in which it is described in the spec file.</li><li>The feature (method) is described in the spec file, but is implemented as an alias of another method.</li></ul></li><li>“moved”: The feature is marked as to be described in a manner different from its implementation. Suppresses “Misplaced” tag.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature13">3.2.2.1. Module Diagrams</h5><div class="feature-contents"><div class="user-item"><div class="p">Each module section has two <span class="italic">module diagrams</span>. For example, the following may appear under the section of a class <code class="inline">B</code>:</div><figure><img alt="Module diagrams" src="spec/module_diagram.png" style="border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 10. Module diagrams</figcaption></figure><div class="p">The first diagram represents mixins and ancestors related to <code class="inline">B</code> itself, and the second one is for its singleton class <code class="inline"><<B</code>. Each bordered area includes exactly one class and zero or more modules it has mixin relations with. The classes are vertically aligned at the same height. A mixin relation is expressed with the character <code class="inline">┊</code>; modules located below the class are the prepended ones, those located above are the included modules. They are ordered so that a lower module/class has priority over a higher one in method call. Thus, the diagram tells that module <code class="inline">C</code> was prepended to class <code class="inline">B</code>, and module <code class="inline">D</code> was included into <code class="inline">B</code>, after which module <code class="inline">E</code> was included into <code class="inline">B</code>. The bordered areas are related with the character <code class="inline"><</code>, which expresses a minimum subclass relation between the respective classes in the bordered areas. The diagram tells that class <code class="inline">B</code> has class <code class="inline">A</code> as its parent. Note that the entire method search path (priority) can be followed by going from the bottom to top, left to right: <code class="inline">C</code> → <code class="inline">B</code> → <code class="inline">E</code> → <code class="inline">D</code> → <code class="inline">A</code> → <code class="inline">Object</code> → <code class="inline">Kernel</code> → <code class="inline">BasicObject</code>. Links are available for navigation to the module sections that are displayed.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature14">3.2.2.2. Alternative Implementations</h5><div class="feature-contents"><div class="user-item"><div class="p">The developer's chart displays information about <span class="italic">alternative implementations</span>. This functionality is intended to help developers test and compare different implementations of a feature by following a convention. Singleton or instance methods implemented in the program code and whose name includes exactly one occurrence of the sequence <code class="inline">__</code> will be considered alternative implementations of the <span class="italic">main implementation</span>, whose name corresponds to the sequence preceding <code class="inline">__</code>. The (possibly empty) sequence following <code class="inline">__</code> is intended to be used as a label for distinguishing each alternative; perhaps a serial number, a few-word summary of the implementation detail, the developer's name, or implementation date can be used. For example, the following methods are all considered alternatives of the main implementation <code class="inline">foo</code>:</div><div class="CodeRay">
|
|
122
|
+
<div class="p">After running Manager, we can see that the warning is gone from <code class="inline">CHART.html</code>, and for <code class="inline">MANUAL.html</code>, by clicking the header “Array#same_counts”, we can see that we now have documentation for the user:</div><figure><img alt="Simple example step 8" src="spec/tutorial_8.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 8. Simple example step 8</figcaption></figure><div class="p">For more examples, please see the spec files of the following gems: manager, dom, pretty_debug, compact_time, and the spec files under the directory <code class="inline">manager/examples</code>.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature5">2.2. Download</h3><div class="feature-contents"><div class="user-item"><div class="p">To install Manager, type the following:</div><div class="CodeRay">
|
|
123
|
+
<div class="code"><pre>$ sudo gem install manager
|
|
124
|
+
</pre></div>
|
|
125
|
+
</div>
|
|
126
|
+
<div class="p">To access the source, goto: <a href="https://github.com/sawa/manager">https://github.com/sawa/manager</a></div><div class="p">Your contribution is welcome. Especially, the followings are wanted:</div><ul><li>A professional quality theme for Manager (Cf. <a href="#feature28">4.1.7. Theme (theme, theme-list)</a>)</li><li>Opinions on structured setup for tests.</li></ul><div class="p">If you are willing to make a contribution, please post an issue on <a href="https://github.com/sawa/manager">https://github.com/sawa/manager</a>. However, not all posts are accepted. It is up to the desicion of the author.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature6">2.3. Release Notes</h3><div class="feature-contents"><div class="user-item"><div class="p">Manager follows semantic versioning, i.e., the first number section of a version (major) corresponds to backwards incompatible API changes, the second number (minor) describes backwards compatible API changes, such as new functionality/features, and the third number (teeny) describes implementation level detail changes, such as small bug fixes.</div><ul><li>0.1.0<ul><li>Initial release.</li></ul></li><li>0.1.1<ul><li>Changed homepage, etc.</li></ul></li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature7">3. Viewing The Files</h2><div class="feature-contents"><div class="user-item"><div class="p">Manager generates two HTML format files: a <span class="italic">user's manual</span> and a <span class="italic">developer's chart</span>. They are to be viewed on a web browser.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature8">3.1. User's Manual</h3><div class="feature-contents"><div class="user-item"><div class="p">User's manual includes <span class="italic">documentation</span> about described or implemented modules and features. It is intended to be read by the users of the software.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature9">3.1.1. Main Information</h4><div class="feature-contents"><div class="user-item"><div class="p">The <span class="italic">main information</span> is displayed in three levels:</div><ul><li><span class="italic">Modules</span> (including classes)</li><li><span class="italic">Features</span> (i.e., constants, singleton methods, instance methods, see <a href="#feature36">5.2.1. Feature</a>) and <span class="italic">section headers</span> (see <a href="#feature38">5.2.3. Section Header</a>)</li><li><span class="italic">Items</span> (contents)</li></ul><div class="p">Features described in the spec as well as features implemented within the listed files (see <a href="#feature32">5.1. Reference to Program Code</a>) will be displayed by modules. Features in the spec file will be placed first and in the order they are described in the spec. However, if the module bodies of a single module (which include feature descriptions) are scattered across multiple locations in the spec file, then they are merged together in the first location. Features implemented but not described in the spec will follow the described ones within their owner modules. They will be described with their original name in case of an alias method.</div><div class="p">Modules, features, and description sections are clickable unless their content is empty. Each one toggles elements that are more detailed than itself between hidden/displayed states. Each feature has a <span class="italic">visibility</span> tag (valued “<span class="italic">Unimplemented</span>”, “<span class="italic">protected</span>”, “<span class="italic">private</span>”, or “<span class="italic">public</span>”) and a numbered <span class="italic">type</span> tag (distinguished by “<span class="italic">Constant</span>”, “<span class="italic">Singleton method</span>”, or “<span class="italic">Instance method</span>”) except for constants that are modules.</div><div class="p">Modules (including classes) within the name space of a module other than <code class="inline">Object</code> are only displayed under the (constant) feature section with a link to where they are displayed as an independent module section. The <code class="inline">Object</code> class is displayed only if it has a feature described in the spec file or if a non-module feature of <code class="inline">Object</code> is implemented in the program code.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature10">3.1.2. Top Bar</h4><div class="feature-contents"><div class="user-item"><div class="p">At the top of the user's manual is the <span class="italic">top bar</span>, which has buttons and information to help users navigate through the file.</div><ul><li>“Modules”, “Features”, and “Full” buttons: Reset the level of detail to be displayed. “Module” button only displays the module names. “Feature” button displays up to the inventory of features as well as the headers of description sections. “Full” button displays to the full detail. Features and items can be further hidden/displayed independently or in groups by other buttons, as to be explained below; the three buttons are only responsible for the level of detail right after they are clicked.</li><li>Visibility buttons: Each button toggles between showing/hiding states of the features with the corresponding visibility. The digits beside each button represent the number of features with the visibility, and remain constant even if any of them become hidden. Buttons with numbers are omitted if the number of features is zero.</li><li>Type buttons: Each button toggles between showing/hiding states of the features of the corresponding type. The digits beside each button represent the number of features of the type, and remain constant even if any of them become hidden. Buttons with numbers are omitted if the number of features is zero.</li></ul><div class="p">The <span class="italic">left/right arrows</span> on the right of a group of buttons allow navigation through features. The numerator on the right side describes the position that was last navigated using the arrow buttons (or “1” by default). If the last navigation was done using the associated arrow buttons, then the number is displayed with emphasis. The denominator describes the number of displayed (i.e. not hidden) features. The number following the plus sign tells the user how many features they are implicitly skipping during navigation; it indicates the number of features hidden for reasons other than any property in the group being hidden. For example, the following situation:</div><figure><img alt="Navigation" src="spec/navigation.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 9. Navigation</figcaption></figure><div class="p">shows that the arrow keys next to the “Unimplemented”/“protected”/“private”/“public” group were the ones last clicked for navigation, and that the current scroll position points to the third feature among the 140 visible ones (features that are not private and not constant) unless the user has further scrolled without using any navigation buttons. As the sum of 11 (Unimplemented), 10 (protected), and 126 (public) is 147, 147 features would be expected to be displayed if nothing but private features were hidden. However, the features are hidden not only because they are private. Since constants are hidden, Unimplemented/protected/public features that are constants are hidden. The number seven after the plus sign in the first group indicates this amount. Similarly, 58 is the number of singleton/instance methods hidden because they are private.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature11">3.2. Developer's Chart</h3><div class="feature-contents"><div class="user-item"><div class="p">The contents of the developer's chart is a superset of that of the user's manual. It includes annotations, test reports, and warnings. It is intended to be utilized by the developers of the software.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature12">3.2.1. Left Panel</h4><div class="feature-contents"><div class="user-item"><div class="p">“Gem Spec” displays information given in a gem spec file if the object of Manager is a gem, and a <a href="#feature151"><code class="inline"><<::#gemspec</code></a> command is called in the spec (see below, <a href="#feature32">5.1. Reference to Program Code</a>).</div><div class="p">The <span class="italic">base directory</span> is the directory in which the spec file resides. Throughout Manager, file names are displayed either as a path relative to the base directory or as an absolute path, whichever is shorter.</div><div class="p">The “Files” table lists information about the relevant files.</div><ul><li>“Category”: Files are classified into the following.<ul><li>“Depended”: Pieces of software that are loaded during Manager run, but are neither the subject nor the object of documentation or test. In particular, the Ruby implementation that is used to run Manager, and any gems that are loaded.</li><li>“Specification”: The subject of description/tests. Also called <span class="italic">spec</span> in this manual/chart.</li><li>“Program”: Files that are the object of analysis/tests. They are described with the percentage of the number of lines covered in tests against the number of all lines in the file.</li></ul></li><li>“Version”: Version is described by the version number for depended files and by the last modified time for specification and program code files. Among the last modified times, the latest one is displayed with emphasis. This may give a hint on which file has mainly undergone modification right before the Manager was run, so that the developer can focus on reading the relevant contents.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature13">3.2.2. Main Information</h4><div class="feature-contents"><div class="user-item"><div class="p">Features in the developer's chart, unlike those in the user's manual, may be tagged by one of the followings that describe <span class="italic">documentation status</span>. They are exclusive (i.e. no feature may be tagged by more than one of them), and are not complementary (i.e. a feature may be tagged by none of them). Among them, “Undocumented” and “Misplaced” are warnings, and “hidden” or “moved” indicate markings in the spec file (see <a href="#feature36">5.2.1. Feature</a>).</div><ul><li>“Undocumented”: The feature is implemented in the program code, but is not described in the spec file.</li><li>“hidden”: The feature is marked in the spec file as to be hidden in the user's manual. This is intended to be used for features that are internal implementations, and are not meant to be public API.</li><li>“Misplaced”: The feature is under one or more of the following three occasions. This tag is suppressed when the feature is marked as “moved”.<ul><li>The feature (method) is implemented within a file that is not listed (see <a href="#feature32">5.1. Reference to Program Code</a> on how to list a feature).</li><li>The feature is implemented on an ancestor module rather than in the module in which it is described in the spec file.</li><li>The feature (method) is described in the spec file, but is implemented as an alias of another method.</li></ul></li><li>“moved”: The feature is marked as to be described in a manner different from its implementation. Suppresses “Misplaced” tag.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature14">3.2.2.1. Module Diagrams</h5><div class="feature-contents"><div class="user-item"><div class="p">Each module section has two <span class="italic">module diagrams</span>. For example, the following may appear under the section of a class <code class="inline">B</code>:</div><figure><img alt="Module diagrams" src="spec/module_diagram.png" style="border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 10. Module diagrams</figcaption></figure><div class="p">The first diagram represents mixins and ancestors related to <code class="inline">B</code> itself, and the second one is for its singleton class <code class="inline"><<B</code>. Each bordered area includes exactly one class and zero or more modules it has mixin relations with. The classes are vertically aligned at the same height. A mixin relation is expressed with the character <code class="inline">┊</code>; modules located below the class are the prepended ones, those located above are the included modules. They are ordered so that a lower module/class has priority over a higher one in method call. Thus, the diagram tells that module <code class="inline">C</code> was prepended to class <code class="inline">B</code>, and module <code class="inline">D</code> was included into <code class="inline">B</code>, after which module <code class="inline">E</code> was included into <code class="inline">B</code>. The bordered areas are related with the character <code class="inline"><</code>, which expresses a minimum subclass relation between the respective classes in the bordered areas. The diagram tells that class <code class="inline">B</code> has class <code class="inline">A</code> as its parent. Note that the entire method search path (priority) can be followed by going from the bottom to top, left to right: <code class="inline">C</code> → <code class="inline">B</code> → <code class="inline">E</code> → <code class="inline">D</code> → <code class="inline">A</code> → <code class="inline">Object</code> → <code class="inline">Kernel</code> → <code class="inline">BasicObject</code>. Links are available for navigation to the module sections that are displayed.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature15">3.2.2.2. Alternative Implementations</h5><div class="feature-contents"><div class="user-item"><div class="p">The developer's chart displays information about <span class="italic">alternative implementations</span>. This functionality is intended to help developers test and compare different implementations of a feature by following a convention. Singleton or instance methods implemented in the program code and whose name includes exactly one occurrence of the sequence <code class="inline">__</code> will be considered alternative implementations of the <span class="italic">main implementation</span>, whose name corresponds to the sequence preceding <code class="inline">__</code>. The (possibly empty) sequence following <code class="inline">__</code> is intended to be used as a label for distinguishing each alternative; perhaps a serial number, a few-word summary of the implementation detail, the developer's name, or implementation date can be used. For example, the following methods are all considered alternatives of the main implementation <code class="inline">foo</code>:</div><div class="CodeRay">
|
|
123
127
|
<div class="code"><pre>foo__
|
|
124
128
|
foo__1
|
|
125
129
|
foo__2
|
|
@@ -131,15 +135,15 @@ foo__20151201
|
|
|
131
135
|
foo__20160101
|
|
132
136
|
</pre></div>
|
|
133
137
|
</div>
|
|
134
|
-
<div class="p">To avoid conflict or confusion with (mostly Ruby core) methods or keywords with balanced <code class="inline">__</code> (such as <code class="inline">__FILE__</code> or <code class="inline">__send__</code>), a method that has more than one <code class="inline">__</code> (such as <code class="inline">foo__map__1</code>) is not considered an alternative implementation.</div><div class="p">Alternative (as well as main) implementations are detected and displayed together after bullets with the title “Implementation candidates” under the feature named for the main implementation. As such, an alternative implementation cannot be described in the spec file as an independent feature. It is possible that alternatives are implemented without the main one being implemented. In such case, the feature header will have the visibility “unimplemented”. Each alternative will have the visibility described within parentheses if the value differs from the main implementation. In this example,</div><figure><img alt="Alternatives with unimplemented main" src="spec/alternatives_unimplemented.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 11. Alternatives with unimplemented main</figcaption></figure><div class="p">instance methods <code class="inline">A#foo__1</code> and <code class="inline">A#foo__2</code> are implemented in the ;program code as private and public methods respectively, but the corresponding main method <code class="inline">A#foo</code> is not implemented. So the feature header has a tag “unimplemented”. In this example,</div><figure><img alt="Alternatives with implemented main" src="spec/alternatives_implemented.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 12. Alternatives with implemented main</figcaption></figure><div class="p">three instance methods <code class="inline">A#bar</code>, <code class="inline">A#bar__1</code>, and <code class="inline">A#bar__2</code> are implemented in the program code. The “public” tag indicates that the main implementation <code class="inline">A#bar</code> is public. <code class="inline">A#bar__1</code> is implemented as a protected method, and the absence of visibility description for <code class="inline">A#bar__2</code> indicates that it is the same as the main implementation, i.e. public.</div><div class="p">In order for alternative implementations to pursue their purpose, their visibility should match that of the main implementation (if implemented). Thus, visibility description in parentheses is indication that the implementation is wrong; the description is intended to work as a warning to the developer.</div><div class="p">On the right side, the source location (i.e. file name and line number) of each implementation is described if it is detectable.</div><div class="p">In one use of this functionality, a main method has already been implemented in a program code file, and the developer wants to test its alternative implementations that appeared afterwards. In such case, it may be better to implement the alternatives in a file different from the main program file or in the scratch code (see <a href="#feature31">5.1. Reference to Program Code</a>) in order not to mess the original code file.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature15">3.2.2.3. Documentation Reports</h5><div class="feature-contents"><div class="user-item"><div class="p">Items in the developer's chart is marked with various <span class="italic">warnings</span>. Appropriate fix should be made when a warning is displayed.</div><ul><li>“Missing”: There are items that a feature described in the spec file should minimally have. If any of the following (see <a href="#feature30">5. Spec File</a>) is missing in a feature documented in the spec file, this tag is displayed. These warnings are suppressed when the feature is marked as “hidden” or “moved”.<ul><li>The feature does not include any unit test.</li><li>The feature does not have any paragraph for the user.</li><li>The feature (method) has no description about its method signature.</li></ul></li><li>Spell errors are shown in distinct type faces (If <code class="inline">spell_check</code> option is on, see <a href="#feature21">4.1.1. Spell Check (spell_check, spell-check-list, spell-check-filter, case_sensitive, case_insensitive)</a>).</li><li>Bad links (see <a href="#feature42">5.3.3. Link</a>) within annotation, test description, list item, citation, or paragraph are shown in distinct type faces. This is also shown in user's manual.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h6 id="feature16">3.2.2.3.1. Annotations and Editorial Markings</h6><div class="feature-contents"><div class="user-item"><div class="p">Whereas documentation describes the Application Programming Interface (API), it is sometimes helpful to have information on the implementation level details of the software. Manager detects <span class="italic">annotations</span> in the spec file and the program code. It also detects comments in the program code that follow a certain format (traces of temporal edits) and regards them as <span class="italic">editorial markings</span>. While documentation should appear in the user's manual, annotations and editorial markings should be hidden from the users and only be displayed in the developer's chart.</div><div class="p">Among annotations and editorial markings, there are two types:</div><ul><li><span class="italic">Agenda</span>: Those that should be kept temporarily and should be aimed to be resolved after some time, such as markings on incomplete or buggy parts of the program code, or commented out parts that are undergoing changes by the developers</li><li><span class="italic">Log</span>: Those that should be kept permanently or for a relatively long time for future reference, such as remarks on the reason a certain algorithm was chosen in the implementation, or the intent of a certain routine</li></ul><div class="p">Different annotations written in the spec file or the program code may be <span class="italic">related</span> by a <span class="italic">tag</span> (see <a href="#feature46">5.3.4. Annotation</a>). For example, a single remark may be made for multiple locations in a program code file, and one may not want to repeat writing the same annotation in each location. Or one may want to annotate something in the spec file about a certain portion of the program code at some location. An annotation tag either has a <span class="italic">file scope</span> or a <span class="italic">method-body scope</span>, and annotations with the same tag within the same scope consist a <span class="italic">set</span> of related annotations and are displayed as one; their contents are joined with a space character, the file names and line numbers are compacted, and the line numbers where the content is taken from are emphasized. A tag is displayed after the locations. Similarly, same types of editorial markings are related per file, and are displayed chart together. Annotations with a file scope are displayed in the main context.</div><div class="p">An assumption made about the development cycle is that annotations can be first written in isolation and free style as temporal annotation (i.e. agenda). Then, as it turns out to be organized information that should be recorded (i.e. log), they should be tagged, and the content should be moved into the spec file, with a tag relating the original location in the program code and the corresponding annotation in the spec file. Based on this, annotations and editorial markings are categorized as agenda or log by the following rule:</div><ul><li>Un-tagged annotations are log.</li><li>Tagged annotations are agenda.</li><li>Editorial markings are agenda.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature17">3.2.2.4. Test Reports</h5><div class="feature-contents"><div class="user-item"><div class="p">A feature can have <span class="italic">tests</span> (unit tests or benchmarks). A unit test is run against each alternative implementation of the feature. A benchmark is run together for the alternative implementations of the feature. Each test results in one of the following in the order of priority given below (for terminology and <a href="#feature115"><code class="inline">::#expr</code></a>, see <a href="#feature53">5.4. Testing</a>):</div><ol><li>If the string argument of <code class="inline">expr</code> cannot be parsed as Ruby code, then the result is “Bad test”.</li><li>If the string argument of <code class="inline">expr</code> within the exercise receiver or arguments of a test cannot be evaluated in the given context, then the result is “Bad test”.</li><li>If the exercise receiver of a test is not an instance (of a subclass) of the module that the feature is described under, then the result is “Untestable”.</li><li>If the feature to be tested is not defined on the exercise receiver, then the result is “Untestable” (if there is an alternative implementation, then the feature is regarded as defined with respect to the test even if the main implementation is not defined).</li><li>If calling the feature on the exercise receiver and arguments raises an error, then the result is “Bug”.</li><li>If the string argument of <code class="inline">expr</code> within the verifying arguments of a test cannot be evaluated in the given context, then the result is “Bad test”.</li><li>If a unit test contingent on another one is not preceded by a successfully exercised unit test, then the result is “Untestable”.</li><li>If calling the tested feature on the exercise result and the verifying arguments raises an unexpected error, then the result is “Bug”.</li><li>If the test is a unit test, and the verification result is falsy, then the result “Bug”.</li><li>The result is “Success”.</li></ol><div class="p">Tests are reported per feature in the following way:</div><ul><li>If a test results in “Bad test” or “Untestable” (for an implementation of the feature), then its report for the entire feature will be as such (“Bad test” or “Untestable”), with a common message.</li><li>If a test results in “Bug” for any implementation of the feature, then its report for the entire feature will be “Bug”. If the test is a unit test, a message is shown under a bullet for each implementation that resulted in “Bug”. If it is a benchmark, a message is shown only for the first implementation that resulted in “Bug”.</li><li>If a test results in “Success” for all implementations of the feature, then “Success” is displayed if it is a unit test, or a graph is shown if it is a benchmark.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature18">3.2.3. Top Bar</h4><div class="feature-contents"><div class="user-item"><div class="p">The top bar in developer's chart is a superset of that of the user's manual. The numbers displayed aside visibility buttons and type buttons may be greater than the corresponding number displayed in the user's manual. This is due to some features being marked as “hidden” (see <a href="#feature35">5.2.1. Feature</a>). In addition to the functionality in the user's manual, the top bar has the following.</div><ul><li>“User Items” button: Toggles <span class="italic">user items</span>, i.e. items that are primarily for the user's manual. Relevant items are in distinct background color when displayed.</li><li>Documentation status buttons (“Undocumented”, “Hidden”, “Misplaced”, “Moved”), documentation report buttons (“Missing doc”, “Bad doc”, “Agenda”, “Log”), and test report buttons (“Missing test”, “Bad test”, “Untestable”, “Bug”, “Success”, “Benchmark”): They work similarly to visibility buttons and type buttons.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature19">4. Running Manager</h2><div class="feature-contents"><div class="user-item"><div class="p">Manager can either be run as a command on the terminal, or be called within a Ruby code.</div><ul><li>To run Manager on the terminal, execute the command <code class="inline">manager</code> with the path to the spec file as an argument. To skip a time-consuming test, type Ctrl+C during the test.</li></ul><div class="CodeRay">
|
|
138
|
+
<div class="p">To avoid conflict or confusion with (mostly Ruby core) methods or keywords with balanced <code class="inline">__</code> (such as <code class="inline">__FILE__</code> or <code class="inline">__send__</code>), a method that has more than one <code class="inline">__</code> (such as <code class="inline">foo__map__1</code>) is not considered an alternative implementation.</div><div class="p">Alternative (as well as main) implementations are detected and displayed together after bullets with the title “Implementation candidates” under the feature named for the main implementation. As such, an alternative implementation cannot be described in the spec file as an independent feature. It is possible that alternatives are implemented without the main one being implemented. In such case, the feature header will have the visibility “unimplemented”. Each alternative will have the visibility described within parentheses if the value differs from the main implementation. In this example,</div><figure><img alt="Alternatives with unimplemented main" src="spec/alternatives_unimplemented.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 11. Alternatives with unimplemented main</figcaption></figure><div class="p">instance methods <code class="inline">A#foo__1</code> and <code class="inline">A#foo__2</code> are implemented in the ;program code as private and public methods respectively, but the corresponding main method <code class="inline">A#foo</code> is not implemented. So the feature header has a tag “unimplemented”. In this example,</div><figure><img alt="Alternatives with implemented main" src="spec/alternatives_implemented.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 12. Alternatives with implemented main</figcaption></figure><div class="p">three instance methods <code class="inline">A#bar</code>, <code class="inline">A#bar__1</code>, and <code class="inline">A#bar__2</code> are implemented in the program code. The “public” tag indicates that the main implementation <code class="inline">A#bar</code> is public. <code class="inline">A#bar__1</code> is implemented as a protected method, and the absence of visibility description for <code class="inline">A#bar__2</code> indicates that it is the same as the main implementation, i.e. public.</div><div class="p">In order for alternative implementations to pursue their purpose, their visibility should match that of the main implementation (if implemented). Thus, visibility description in parentheses is indication that the implementation is wrong; the description is intended to work as a warning to the developer.</div><div class="p">On the right side, the source location (i.e. file name and line number) of each implementation is described if it is detectable.</div><div class="p">In one use of this functionality, a main method has already been implemented in a program code file, and the developer wants to test its alternative implementations that appeared afterwards. In such case, it may be better to implement the alternatives in a file different from the main program file or in the scratch code (see <a href="#feature32">5.1. Reference to Program Code</a>) in order not to mess the original code file.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature16">3.2.2.3. Documentation Reports</h5><div class="feature-contents"><div class="user-item"><div class="p">Items in the developer's chart is marked with various <span class="italic">warnings</span>. Appropriate fix should be made when a warning is displayed.</div><ul><li>“Missing”: There are items that a feature described in the spec file should minimally have. If any of the following (see <a href="#feature31">5. Spec File</a>) is missing in a feature documented in the spec file, this tag is displayed. These warnings are suppressed when the feature is marked as “hidden” or “moved”.<ul><li>The feature does not include any unit test.</li><li>The feature does not have any paragraph for the user.</li><li>The feature (method) has no description about its method signature.</li></ul></li><li>Spell errors are shown in distinct type faces (If <code class="inline">spell_check</code> option is on, see <a href="#feature22">4.1.1. Spell Check (spell_check, spell-check-list, spell-check-filter, case_sensitive, case_insensitive)</a>).</li><li>Bad links (see <a href="#feature43">5.3.3. Link</a>) within annotation, test description, list item, citation, or paragraph are shown in distinct type faces. This is also shown in user's manual.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h6 id="feature17">3.2.2.3.1. Annotations and Editorial Markings</h6><div class="feature-contents"><div class="user-item"><div class="p">Whereas documentation describes the Application Programming Interface (API), it is sometimes helpful to have information on the implementation level details of the software. Manager detects <span class="italic">annotations</span> in the spec file and the program code. It also detects comments in the program code that follow a certain format (traces of temporal edits) and regards them as <span class="italic">editorial markings</span>. While documentation should appear in the user's manual, annotations and editorial markings should be hidden from the users and only be displayed in the developer's chart.</div><div class="p">Among annotations and editorial markings, there are two types:</div><ul><li><span class="italic">Agenda</span>: Those that should be kept temporarily and should be aimed to be resolved after some time, such as markings on incomplete or buggy parts of the program code, or commented out parts that are undergoing changes by the developers</li><li><span class="italic">Log</span>: Those that should be kept permanently or for a relatively long time for future reference, such as remarks on the reason a certain algorithm was chosen in the implementation, or the intent of a certain routine</li></ul><div class="p">Different annotations written in the spec file or the program code may be <span class="italic">related</span> by a <span class="italic">tag</span> (see <a href="#feature47">5.3.4. Annotation</a>). For example, a single remark may be made for multiple locations in a program code file, and one may not want to repeat writing the same annotation in each location. Or one may want to annotate something in the spec file about a certain portion of the program code at some location. An annotation tag either has a <span class="italic">file scope</span> or a <span class="italic">method-body scope</span>, and annotations with the same tag within the same scope consist a <span class="italic">set</span> of related annotations and are displayed as one; their contents are joined with a space character, the file names and line numbers are compacted, and the line numbers where the content is taken from are emphasized. A tag is displayed after the locations. Similarly, same types of editorial markings are related per file, and are displayed chart together. Annotations with a file scope are displayed in the main context.</div><div class="p">An assumption made about the development cycle is that annotations can be first written in isolation and free style as temporal annotation (i.e. agenda). Then, as it turns out to be organized information that should be recorded (i.e. log), they should be tagged, and the content should be moved into the spec file, with a tag relating the original location in the program code and the corresponding annotation in the spec file. Based on this, annotations and editorial markings are categorized as agenda or log by the following rule:</div><ul><li>Un-tagged annotations are log.</li><li>Tagged annotations are agenda.</li><li>Editorial markings are agenda.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature18">3.2.2.4. Test Reports</h5><div class="feature-contents"><div class="user-item"><div class="p">A feature can have <span class="italic">tests</span> (unit tests or benchmarks). A unit test is run against each alternative implementation of the feature. A benchmark is run together for the alternative implementations of the feature. Each test results in one of the following in the order of priority given below (for terminology and <a href="#feature116"><code class="inline">::#expr</code></a>, see <a href="#feature54">5.4. Testing</a>):</div><ol><li>If the string argument of <code class="inline">expr</code> cannot be parsed as Ruby code, then the result is “Bad test”.</li><li>If the string argument of <code class="inline">expr</code> within the exercise receiver or arguments of a test cannot be evaluated in the given context, then the result is “Bad test”.</li><li>If the exercise receiver of a test is not an instance (of a subclass) of the module that the feature is described under, then the result is “Untestable”.</li><li>If the feature to be tested is not defined on the exercise receiver, then the result is “Untestable” (if there is an alternative implementation, then the feature is regarded as defined with respect to the test even if the main implementation is not defined).</li><li>If calling the feature on the exercise receiver and arguments raises an error, then the result is “Bug”.</li><li>If the string argument of <code class="inline">expr</code> within the verifying arguments of a test cannot be evaluated in the given context, then the result is “Bad test”.</li><li>If a unit test contingent on another one is not preceded by a successfully exercised unit test, then the result is “Untestable”.</li><li>If calling the tested feature on the exercise result and the verifying arguments raises an unexpected error, then the result is “Bug”.</li><li>If the test is a unit test, and the verification result is falsy, then the result “Bug”.</li><li>The result is “Success”.</li></ol><div class="p">Tests are reported per feature in the following way:</div><ul><li>If a test results in “Bad test” or “Untestable” (for an implementation of the feature), then its report for the entire feature will be as such (“Bad test” or “Untestable”), with a common message.</li><li>If a test results in “Bug” for any implementation of the feature, then its report for the entire feature will be “Bug”. If the test is a unit test, a message is shown under a bullet for each implementation that resulted in “Bug”. If it is a benchmark, a message is shown only for the first implementation that resulted in “Bug”.</li><li>If a test results in “Success” for all implementations of the feature, then “Success” is displayed if it is a unit test, or a graph is shown if it is a benchmark.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature19">3.2.3. Top Bar</h4><div class="feature-contents"><div class="user-item"><div class="p">The top bar in developer's chart is a superset of that of the user's manual. The numbers displayed aside visibility buttons and type buttons may be greater than the corresponding number displayed in the user's manual. This is due to some features being marked as “hidden” (see <a href="#feature36">5.2.1. Feature</a>). In addition to the functionality in the user's manual, the top bar has the following.</div><ul><li>“User Items” button: Toggles <span class="italic">user items</span>, i.e. items that are primarily for the user's manual. Relevant items are in distinct background color when displayed.</li><li>Documentation status buttons (“Undocumented”, “Hidden”, “Misplaced”, “Moved”), documentation report buttons (“Missing doc”, “Bad doc”, “Agenda”, “Log”), and test report buttons (“Missing test”, “Bad test”, “Untestable”, “Bug”, “Success”, “Benchmark”): They work similarly to visibility buttons and type buttons.</li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature20">4. Running Manager</h2><div class="feature-contents"><div class="user-item"><div class="p">Manager can either be run as a command on the terminal, or be called within a Ruby code.</div><ul><li>To run Manager on the terminal, execute the command <code class="inline">manager</code> with the path to the spec file as an argument. To skip a time-consuming test, type Ctrl+C during the test.</li></ul><div class="CodeRay">
|
|
135
139
|
<div class="code"><pre>$ manager some_directory/spec_file
|
|
136
140
|
</pre></div>
|
|
137
141
|
</div>
|
|
138
|
-
<ul><li>To run Manager within in a Ruby code, execute the method <a href="#
|
|
142
|
+
<ul><li>To run Manager within in a Ruby code, execute the method <a href="#feature81"><code class="inline">Manager.new</code></a> with the path to the spec file as an argument.</li></ul><div class="CodeRay">
|
|
139
143
|
<div class="code"><pre><span class="constant">Manager</span>.new(<span class="string"><span class="delimiter">"</span><span class="content">some_directory/spec_file</span><span class="delimiter">"</span></span>)
|
|
140
144
|
</pre></div>
|
|
141
145
|
</div>
|
|
142
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="
|
|
146
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature21">4.1. Customization and Options</h3><div class="feature-contents"><div class="user-item"><div class="p">Customization is done either through a command line option using a double hyphen <code class="inline">--</code> before a key, possibly followed by the value, or through the <a href="#feature69"><code class="inline">Manager.config</code></a> method in the spec file with a symbol key and a value. The options in this section are given for <code class="inline">Manager.config</code>. To use them in the command line, read underscores <code class="inline">_</code> in them as hyphens <code class="inline">-</code>. Multiple options can be specified with a single command/method. When an option is specified in both ways, the command line option overrides the <code class="inline">config</code> method.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature22">4.1.1. Spell Check (spell_check, spell-check-list, spell-check-filter, case_sensitive, case_insensitive)</h4><div class="feature-contents"><div class="user-item"><div class="p">Spell checking is available if the <code class="inline">ffi-aspell</code> gem and the relevant natural language component are installed. The inventory of available languages is shown in the command line by the <code class="inline">--spell-check-list</code> option:</div><div class="CodeRay">
|
|
143
147
|
<div class="code"><pre>$ manager --spell-check-list
|
|
144
148
|
</pre></div>
|
|
145
149
|
</div>
|
|
@@ -170,7 +174,7 @@ prepend
|
|
|
170
174
|
</span><span class="delimiter">]</span></span>
|
|
171
175
|
</pre></div>
|
|
172
176
|
</div>
|
|
173
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
177
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature23">4.1.2. Output Directory (odir)</h4><div class="feature-contents"><div class="user-item"><div class="p">The output directory is by default the directory of the spec file. To override this, use the <code class="inline">odir</code> option. Relative path can be used. In such case, it will be expanded relative to the directory of the spec file.</div><div class="CodeRay">
|
|
174
178
|
<div class="code"><pre>$ manager some-directory/spec-file --odir ../documents
|
|
175
179
|
</pre></div>
|
|
176
180
|
</div>
|
|
@@ -178,7 +182,7 @@ prepend
|
|
|
178
182
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">odir</span>: <span class="string"><span class="delimiter">"</span><span class="content">../documents</span><span class="delimiter">"</span></span>
|
|
179
183
|
</pre></div>
|
|
180
184
|
</div>
|
|
181
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
185
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature24">4.1.3. User's Manual File Name (user)</h4><div class="feature-contents"><div class="user-item"><div class="p">The user's manual is written as the file name <code class="inline">MANUAL.html</code> by default. To override this, use the <code class="inline">user</code> option.</div><div class="CodeRay">
|
|
182
186
|
<div class="code"><pre>$ manager some-directory/spec-file --user README.html
|
|
183
187
|
</pre></div>
|
|
184
188
|
</div>
|
|
@@ -186,7 +190,7 @@ prepend
|
|
|
186
190
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">user</span>: <span class="string"><span class="delimiter">"</span><span class="content">README.html</span><span class="delimiter">"</span></span>
|
|
187
191
|
</pre></div>
|
|
188
192
|
</div>
|
|
189
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
193
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature25">4.1.4. Developer's Chart File Name (dev)</h4><div class="feature-contents"><div class="user-item"><div class="p">The developer's chart is written as the file name <code class="inline">CHART.html</code> by default. To override this, use the <code class="inline">dev</code> option.</div><div class="CodeRay">
|
|
190
194
|
<div class="code"><pre>$ manager some-directory/spec-file --dev result.html
|
|
191
195
|
</pre></div>
|
|
192
196
|
</div>
|
|
@@ -194,7 +198,7 @@ prepend
|
|
|
194
198
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">dev</span>: <span class="string"><span class="delimiter">"</span><span class="content">result.html</span><span class="delimiter">"</span></span>
|
|
195
199
|
</pre></div>
|
|
196
200
|
</div>
|
|
197
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
201
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature26">4.1.5. Title (title)</h4><div class="feature-contents"><div class="user-item"><div class="p">A certain string is used as part of the title to describe what the user's manual and developer's chart are about. By default, the directory name of the spec file is used in hope that in many cases, that should describe the software's project name. To override this, use the <code class="inline">title</code> option.</div><div class="CodeRay">
|
|
198
202
|
<div class="code"><pre>$ manager some-directory/spec-file --title Foo\ Software
|
|
199
203
|
</pre></div>
|
|
200
204
|
</div>
|
|
@@ -202,7 +206,7 @@ prepend
|
|
|
202
206
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">title</span>: <span class="string"><span class="delimiter">"</span><span class="content">Foo Software</span><span class="delimiter">"</span></span>
|
|
203
207
|
</pre></div>
|
|
204
208
|
</div>
|
|
205
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
209
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature27">4.1.6. Base Directory (bdir)</h4><div class="feature-contents"><div class="user-item"><div class="p">The base directory is the reference point for describing relative file names in the output. It does not affect <code class="inline">require</code>/<code class="inline">load</code> commands or the like. By default, it is the directory of the spec file. To override this, use the <code class="inline">bdir</code> option. Relative path can be used. In such case, it will be expanded relative to the directory of the spec file.</div><div class="CodeRay">
|
|
206
210
|
<div class="code"><pre>$ manager some-directory/spec-file --bdir ../lib
|
|
207
211
|
</pre></div>
|
|
208
212
|
</div>
|
|
@@ -210,7 +214,7 @@ prepend
|
|
|
210
214
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">bdir</span>: <span class="string"><span class="delimiter">"</span><span class="content">../lib</span><span class="delimiter">"</span></span>
|
|
211
215
|
</pre></div>
|
|
212
216
|
</div>
|
|
213
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
217
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature28">4.1.7. Theme (theme, theme-list)</h4><div class="feature-contents"><div class="user-item"><div class="p">The design of the output files are controlled by a theme. New themes are occasionally added to Manager gem within version updates. Each theme is described as a CSS format file, and is named after a four digit number describing the publishing year, followed by a letter (starting from <code class="inline">a</code> and incremented) to distinguish multiple designs in a single year, followed by the <code class="inline">.css</code> extension. In addition, another CSS format file describes the part of the design related to syntax highlighting of the code blocks (see <a href="#feature29">4.1.8. Syntax Highlighting (highlight, highlight-list)</a>). These files are incorporated as part of the output HTML files. The inventory of available theme files and highlight files can be accessed from the command line by the <code class="inline">theme-list</code> option.</div><div class="CodeRay">
|
|
214
218
|
<div class="code"><pre>$ manager --theme-list
|
|
215
219
|
</pre></div>
|
|
216
220
|
</div>
|
|
@@ -254,7 +258,7 @@ prepend
|
|
|
254
258
|
...
|
|
255
259
|
</pre></div>
|
|
256
260
|
</div>
|
|
257
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
261
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature29">4.1.8. Syntax Highlighting (highlight, highlight-list)</h4><div class="feature-contents"><div class="user-item"><div class="p">To select a design for syntax highlighting of code blocks, use the <code class="inline">highlight</code> option with the highlight file name.</div><div class="CodeRay">
|
|
258
262
|
<div class="code"><pre>$ manager some-directory/spec-file --highlight coderay_github.css
|
|
259
263
|
</pre></div>
|
|
260
264
|
</div>
|
|
@@ -262,11 +266,11 @@ prepend
|
|
|
262
266
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">highlight</span>: <span class="string"><span class="delimiter">"</span><span class="content">coderay_github.css</span><span class="delimiter">"</span></span>
|
|
263
267
|
</pre></div>
|
|
264
268
|
</div>
|
|
265
|
-
<div class="p">To add a highlight design, place the file within the directory <code class="inline">manager/theme</code>.</div><div class="p">To obtain the list of symbols for the languages that can be highlighted, use the <code class="inline">highlight-list</code> option (see <a href="#
|
|
269
|
+
<div class="p">To add a highlight design, place the file within the directory <code class="inline">manager/theme</code>.</div><div class="p">To obtain the list of symbols for the languages that can be highlighted, use the <code class="inline">highlight-list</code> option (see <a href="#feature51">5.3.8. Code Block</a> for its usage).</div><div class="CodeRay">
|
|
266
270
|
<div class="code"><pre>$ manager --highlight-list
|
|
267
271
|
</pre></div>
|
|
268
272
|
</div>
|
|
269
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
273
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature30">4.1.9. Debugging of Manager (debug)</h4><div class="feature-contents"><div class="user-item"><div class="p">This is not intended for normal use. When the <code class="inline">debug</code> option takes the <code class="inline">true</code> value as follows,</div><div class="CodeRay">
|
|
270
274
|
<div class="code"><pre>$ manager some-directory/spec-file --debug true
|
|
271
275
|
</pre></div>
|
|
272
276
|
</div>
|
|
@@ -274,11 +278,11 @@ prepend
|
|
|
274
278
|
<div class="code"><pre><span class="constant">Manager</span>.config <span class="key">debug</span>: <span class="predefined-constant">true</span>
|
|
275
279
|
</pre></div>
|
|
276
280
|
</div>
|
|
277
|
-
<div class="p">it has the following effects:</div><ol><li>Errors raised by running a spec file and reported on the command line will have backtraces including files internal to Manager. By default, such detailed outputs are suppressed.</li><li>Outputs to standard output and standard error due to running tests are displayed on the command line. By default, they are redirected and are displayed in the output section of test reports.</li><li>Files internal to Manager are displayed in backtraces in test reports when an error or a bug is detected. By default, they are excluded.</li></ol></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
281
|
+
<div class="p">it has the following effects:</div><ol><li>Errors raised by running a spec file and reported on the command line will have backtraces including files internal to Manager. By default, such detailed outputs are suppressed.</li><li>Outputs to standard output and standard error due to running tests are displayed on the command line. By default, they are redirected and are displayed in the output section of test reports.</li><li>Files internal to Manager are displayed in backtraces in test reports when an error or a bug is detected. By default, they are excluded.</li></ol></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature31">5. Spec File</h2><div class="feature-contents"><div class="user-item"><div class="p">Documentation and Tests are written in a spec file. When the spec file contains some higher level errors, they will be reported in the developer's chart in the manner mentioned in <a href="#feature16">3.2.2.3. Documentation Reports</a>, but when there is a syntax error or some low level error, Manager will terminate with an error message without generating any file. In order to feed back the source location of a string in case of an error, Manager stores some objects taken from the spec file with the source location. Particularly, it is important to set the strings in the spec file to be mutable in order for Manager to fully function. Especially under future Ruby 3.0, where strings are frozen by default, it is necessary to ensure this by placing a frozen string pragma with the <code class="inline">false</code> value at the beginning of the spec file:</div><div class="CodeRay">
|
|
278
282
|
<div class="code"><pre><span class="comment"># frozen_string_literal: false</span>
|
|
279
283
|
</pre></div>
|
|
280
284
|
</div>
|
|
281
|
-
<div class="p">Specification can be divided in multiple files as long as there is a single main spec file whose name is directly passed as an argument to the <code class="inline">manager</code> command or <a href="#
|
|
285
|
+
<div class="p">Specification can be divided in multiple files as long as there is a single main spec file whose name is directly passed as an argument to the <code class="inline">manager</code> command or <a href="#feature81"><code class="inline">Manager.new</code></a> method, which loads the other spec files.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature32">5.1. Reference to Program Code</h3><div class="feature-contents"><div class="user-item"><div class="p">Program code can be written in files different from the spec file or in the same file as the (main) spec file as <span class="italic">scratch code</span>, or in combination of both. A program and spec should be normally written in separate files, but in order to do a quick test with a short snippet of code, using scratch code is convenient.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature33">5.1.1. Listing A File</h4><div class="feature-contents"><div class="user-item"><div class="p">In order for a program code file to be the object of analysis by Manager, it has to be <span class="italic">listed</span> in the spec file. Listing a file has two effects:</div><ol><li>The file becomes the object of analysis, i.e. constants and methods implemented in the file will be detected by Manager, and will be displayed (even if they are not described in the spec file).</li><li>The file is marked as one of the locations where the constants and methods described in the spec file are expected to reside. Any feature that has an unlisted source location is marked as “Misplaced” (see <a href="#feature13">3.2.2. Main Information</a>).</li></ol><div class="p">To list a program file, pass its path as an argument to <code class="inline">manage</code> method in the spec file in a position before the specifications. The file path may be either absolute or be relative to the spec file. A program file <code class="inline">foo.rb</code> may internally load a subfile <code class="inline">bar.rb</code>. If <code class="inline">bar.rb</code> is to be the object of analysis, it has to listed in the spec file (after <code class="inline">foo.rb</code>). The beginning of a spec file may look like this:</div><div class="CodeRay">
|
|
282
286
|
<div class="code"><pre><span class="comment"># frozen_string_literal: false</span>
|
|
283
287
|
manage <span class="string"><span class="delimiter">"</span><span class="content">foo.rb</span><span class="delimiter">"</span></span>
|
|
284
288
|
manage <span class="string"><span class="delimiter">"</span><span class="content">bar.rb</span><span class="delimiter">"</span></span>
|
|
@@ -297,7 +301,7 @@ manage <span class="string"><span class="delimiter">"</span><span class="co
|
|
|
297
301
|
<div class="code"><pre>manage <span class="predefined-constant">nil</span>
|
|
298
302
|
</pre></div>
|
|
299
303
|
</div>
|
|
300
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
304
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature34">5.1.2. Scratch Code</h4><div class="feature-contents"><div class="user-item"><div class="p">Scratch code should appear within the main spec file after the line <code class="inline">__END__</code> after the spec code. Writing in this order encourages test driven development (see <a href="#feature4">2.1. Simple Example</a> for examples).</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature35">5.2. The <code class="inline">spec</code> method</h3><div class="feature-contents"><div class="user-item"><div class="p">Description in Manager is done in units using the method <a href="#feature159"><code class="inline">Module#spec</code></a> (This method can appear in the main environment as well as in a module body). The <code class="inline">spec</code> method is placed in a <span class="italic">context</span>, i.e, a module (including class) body or the main environment. It takes a <span class="italic">label</span>, which must be either of the following:</div><ol><li>A string starting with <code class="inline">::</code>, which represents a constant (including modules, classes)</li><li>A string starting with <code class="inline">.</code>, which represents a singleton method</li><li>A string starting with <code class="inline">#</code>, which represents an instance method</li><li>A string starting with one or more consecutive <code class="inline">=</code>s and has no other <code class="inline">=</code>, which represents a description with a numbered section header</li><li><code class="inline">nil</code>, which represents a description without a section header</li></ol><div class="p">followed by an arbitrary number of items (explained in <a href="#feature40">5.3. Documentation</a> and <a href="#feature54">5.4. Testing</a>), and ends with a pseudo-keyword <a href="#feature160"><code class="inline">Module#coda</code></a>. 1–3 above describe a feature, and 4,5 describe a section header. The recommended way of writing descriptions looks like this (empty lines between <code class="inline">coda</code> and the next <code class="inline">spec</code> are optional):</div><div class="CodeRay">
|
|
301
305
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">A</span>
|
|
302
306
|
spec <span class="predefined-constant">nil</span>,
|
|
303
307
|
<span class="string"><span class="delimiter">"</span><span class="content">This class provides API for doing foos.</span><span class="delimiter">"</span></span>,
|
|
@@ -316,13 +320,13 @@ manage <span class="string"><span class="delimiter">"</span><span class="co
|
|
|
316
320
|
<span class="keyword">end</span>
|
|
317
321
|
</pre></div>
|
|
318
322
|
</div>
|
|
319
|
-
<div class="p">which may result in a user's manual that looks like this:</div><figure><img alt="Example of `spec`" src="spec/spec_example.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 13. Example of <code class="inline">spec</code></figcaption></figure><div class="p">The <code class="inline">spec</code> method requires its final argument to be the pseudo-keyword <code class="inline">coda</code>, which is similar to, but different from, the <code class="inline">end</code> keyword of Ruby syntax. This design serves two purposes:</div><ol><li>All items passed to the <code class="inline">spec</code> method uniformly have to be appended by a comma <code class="inline">,</code>, which makes it easier for writing or modifying a spec file; the writer does not have to think whether or not to put a comma depending on whether the item is the last one.</li><li>Without this requirement, an item may be unintentionally skipped because of a forgotten comma after the preceding item. It makes it easier to detect such mistakes.</li></ol><div class="p">The order of the items passed to <code class="inline">spec</code> is respected in the generated files, but when the same feature is described under multiple calls of the <code class="inline">spec</code> method, all items will be gathered at the position of the first <code class="inline">spec</code> call of the feature.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
323
|
+
<div class="p">which may result in a user's manual that looks like this:</div><figure><img alt="Example of `spec`" src="spec/spec_example.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 13. Example of <code class="inline">spec</code></figcaption></figure><div class="p">The <code class="inline">spec</code> method requires its final argument to be the pseudo-keyword <code class="inline">coda</code>, which is similar to, but different from, the <code class="inline">end</code> keyword of Ruby syntax. This design serves two purposes:</div><ol><li>All items passed to the <code class="inline">spec</code> method uniformly have to be appended by a comma <code class="inline">,</code>, which makes it easier for writing or modifying a spec file; the writer does not have to think whether or not to put a comma depending on whether the item is the last one.</li><li>Without this requirement, an item may be unintentionally skipped because of a forgotten comma after the preceding item. It makes it easier to detect such mistakes.</li></ol><div class="p">The order of the items passed to <code class="inline">spec</code> is respected in the generated files, but when the same feature is described under multiple calls of the <code class="inline">spec</code> method, all items will be gathered at the position of the first <code class="inline">spec</code> call of the feature.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature36">5.2.1. Feature</h4><div class="feature-contents"><div class="user-item"><div class="p">By default, a feature description is expected to have:</div><ul><li>At least one paragraph (see <a href="#feature42">5.3.2. Paragraph</a>) and</li><li>At least one unit test (see <a href="#feature55">5.4.1. Unit Test</a>).</li></ul><div class="p">Additionally, a feature that is a method is expected to have:</div><ul><li>At least one method signature (see <a href="#feature41">5.3.1. Method Signature</a>).</li></ul><div class="p">If a feature description lacks a paragraph (or a method signature), then by default it is tagged as “Missing doc”. If a feature description lacks a unit test, then by default it is tagged as “Missing test”.</div><div class="p">Depending on the implementation and description status, a feature may be marked as follows:</div><ul><li>A feature that is described in the spec file but is not implemented in the program code is marked its visibility as “Unimplemented” (see <a href="#feature9">3.1.1. Main Information</a>).</li><li>A feature that is not described but is implemented is, by default, marked as “Undocumented” (see <a href="#feature13">3.2.2. Main Information</a>).</li><li>A feature that is described and is implemented is, by default, expected to confirm to the followings. If it violates any, then by default it is marked as “Misplaced”.<ul><li>Be defined within one of the files listed (see <a href="#feature33">5.1.1. Listing A File</a>) or in scratch code (see <a href="#feature34">5.1.2. Scratch Code</a>),</li><li>Belong to the module it is described under (i.e. not by inheritance), and</li><li>Not be an alias method (Aliases are shown with the main method).</li></ul></li></ul></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature37">5.2.2. Hiding or Moving A Feature</h4><div class="feature-contents"><div class="user-item"><div class="p">Placing the <a href="#feature157"><code class="inline">Module#hide</code></a> method before <code class="inline">spec</code> hides the feature in the user's manual (but not in the developer's chart), and exempts the feature from “Missing doc” and “Missing test” tags.</div><div class="CodeRay">
|
|
320
324
|
<div class="code"><pre>hide spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
321
325
|
...,
|
|
322
326
|
coda
|
|
323
327
|
</pre></div>
|
|
324
328
|
</div>
|
|
325
|
-
<div class="p">Placing either the <code class="inline">hide</code> method or the <a href="#
|
|
329
|
+
<div class="p">Placing either the <code class="inline">hide</code> method or the <a href="#feature158"><code class="inline">Module#move</code></a> method before <code class="inline">spec</code> indicates that such violation is intended, and exempts the feature from “Undocumented” and “Misplaced” markings.</div><div class="CodeRay">
|
|
326
330
|
<div class="code"><pre>move spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
327
331
|
...,
|
|
328
332
|
coda
|
|
@@ -354,7 +358,7 @@ coda
|
|
|
354
358
|
<span class="keyword">end</span>
|
|
355
359
|
</pre></div>
|
|
356
360
|
</div>
|
|
357
|
-
<div class="p">will make <code class="inline">A</code>, <code class="inline">A#foo_a</code>, <code class="inline">B</code>, and <code class="inline">B#foo_b</code> moved, and <code class="inline">A#bar_a</code> and <code class="inline">B#bar_b</code> hidden.</div><div class="p">The methods <code class="inline">hide</code> and <code class="inline">move</code> should be used to hide implementation details in the user's manual. If some features are implemented not for the user's use, but for internal use, then they should be hidden from the user by the <code class="inline">hide</code> method. If some features are implemented under a module <code class="inline">A</code> aimed for developers, which is included in, or prepended to, some modules <code class="inline">B</code> and <code class="inline">C</code> aimed for the users, then <code class="inline">A</code> should be marked by <code class="inline">hide</code>, and <code class="inline">B</code> and <code class="inline">C</code> should be marked by <code class="inline">move</code>.</div><div class="p">A hidden feature cannot include a user item (Cf. <a href="#
|
|
361
|
+
<div class="p">will make <code class="inline">A</code>, <code class="inline">A#foo_a</code>, <code class="inline">B</code>, and <code class="inline">B#foo_b</code> moved, and <code class="inline">A#bar_a</code> and <code class="inline">B#bar_b</code> hidden.</div><div class="p">The methods <code class="inline">hide</code> and <code class="inline">move</code> should be used to hide implementation details in the user's manual. If some features are implemented not for the user's use, but for internal use, then they should be hidden from the user by the <code class="inline">hide</code> method. If some features are implemented under a module <code class="inline">A</code> aimed for developers, which is included in, or prepended to, some modules <code class="inline">B</code> and <code class="inline">C</code> aimed for the users, then <code class="inline">A</code> should be marked by <code class="inline">hide</code>, and <code class="inline">B</code> and <code class="inline">C</code> should be marked by <code class="inline">move</code>.</div><div class="p">A hidden feature cannot include a user item (Cf. <a href="#feature19">3.2.3. Top Bar</a>. See subsections in <a href="#feature40">5.3. Documentation</a> for whether an item is a user item. No item under <a href="#feature54">5.4. Testing</a> is a user item).</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature38">5.2.3. Section Header</h4><div class="feature-contents"><div class="user-item"><div class="p">Section header starts a section about a module or the entire software (if written in the main environment). If the label passed to <code class="inline">spec</code> is <code class="inline">nil</code>, then the section does not have an explicit header. If the label starts with <code class="inline">=</code>, then the header is numbered, and has the content that is the substring following the <code class="inline">=</code>s. Header numbering has hierarchy; the number of <code class="inline">=</code> characters describes the depth of the numbering (one, outermost level to fifth, innermost level). If that is more than five, then, it will be set to the fifth depth.</div><div class="p">No two numbered headers in a sibling position to each other in the same module can have the same content. This is an example of an invalid heading:</div><div class="CodeRay">
|
|
358
362
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">A</span>
|
|
359
363
|
spec <span class="string"><span class="delimiter">"</span><span class="content">=About Foo</span><span class="delimiter">"</span></span>,
|
|
360
364
|
coda
|
|
@@ -394,7 +398,7 @@ coda
|
|
|
394
398
|
<span class="keyword">end</span>
|
|
395
399
|
</pre></div>
|
|
396
400
|
</div>
|
|
397
|
-
<div class="p">and will be displayed as:</div><figure><img alt="Valid Heading" src="spec/valid_heading.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 14. Valid Heading</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
401
|
+
<div class="p">and will be displayed as:</div><figure><img alt="Valid Heading" src="spec/valid_heading.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 14. Valid Heading</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature39">5.2.4. Main Context</h4><div class="feature-contents"><div class="user-item"><div class="p">In Ruby code, methods and constants defined in the main context are owned by the <code class="inline">Object</code> class, hence with respect to the ownership (but not for visibility), it would not make a difference if they were defined in an <code class="inline">Object</code> class body. Manager handles feature descriptions in the same way; describing a feature in the main context is equivalent to describing it within the <code class="inline">Object</code> class body.</div><div class="p">However, Manager distinguishes between describing a section header in the main context and describing it within the <code class="inline">Object</code> class body. The former should be used to describe the entire software, whereas the latter should be done to describe particularly the <code class="inline">Object</code> class.</div><div class="p">In the following example,</div><div class="CodeRay">
|
|
398
402
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">=About This Software</span><span class="delimiter">"</span></span>,
|
|
399
403
|
<span class="string"><span class="delimiter">"</span><span class="content">To install, type `gem install foo`.</span><span class="delimiter">"</span></span>,
|
|
400
404
|
coda
|
|
@@ -414,7 +418,7 @@ coda
|
|
|
414
418
|
<span class="keyword">end</span>
|
|
415
419
|
</pre></div>
|
|
416
420
|
</div>
|
|
417
|
-
<div class="p">the main context and the <code class="inline">Object</code> class each has a section header and a feature description. It is rendered as:</div><figure><img alt="Main context and Object" src="spec/main_and_object.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 15. Main context and Object</figcaption></figure><div class="p">The descriptions for the instance method <code class="inline">bar</code>, which is scattered between the main context and <code class="inline">Object</code> in the spec file, have been combined within <code class="inline">Object</code> under a single feature header <code class="inline">bar</code>, whereas the section headers in main and <code class="inline">Object</code> appear separately.</div></div></div></div><div class="feature"><h3 id="
|
|
421
|
+
<div class="p">the main context and the <code class="inline">Object</code> class each has a section header and a feature description. It is rendered as:</div><figure><img alt="Main context and Object" src="spec/main_and_object.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 15. Main context and Object</figcaption></figure><div class="p">The descriptions for the instance method <code class="inline">bar</code>, which is scattered between the main context and <code class="inline">Object</code> in the spec file, have been combined within <code class="inline">Object</code> under a single feature header <code class="inline">bar</code>, whereas the section headers in main and <code class="inline">Object</code> appear separately.</div></div></div></div><div class="feature"><h3 id="feature40">5.3. Documentation</h3><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature41">5.3.1. Method Signature</h4><div class="feature-contents"><div class="user-item"><div class="p">A method signature is a user item.</div><div class="p">Method signature is described by a hash, with a string key describing arguments and the value describing a (range of) return value. The return value may be described by a class to which the return value belongs to, or by the <a href="#feature161"><code class="inline">Module#value</code></a> method with the argument <code class="inline">obj</code>, which describes the return value as a particular object <code class="inline">obj</code>, or by the <a href="#feature162"><code class="inline">Module#error</code></a> method with the argument <code class="inline">exception_class</code> that describes a class of exceptions that may be raised. Multiple types of return values may be joined by the method <a href="#feature167"><code class="inline">Class#|</code></a> to express alternatives. (The parentheses around the argument of <code class="inline">value</code> or <code class="inline">error</code> should not be omitted, as <code class="inline">|</code> has stronger associativity than method call.)</div><div class="CodeRay">
|
|
418
422
|
<div class="code"><pre>{<span class="string"><span class="delimiter">"</span><span class="content">(str, *arr)</span><span class="delimiter">"</span></span> => value(<span class="integer">-1</span>) | value(<span class="integer">0</span>) | value(<span class="integer">1</span>) | <span class="constant">Array</span> | error(<span class="constant">ArgumentError</span>)}
|
|
419
423
|
</pre></div>
|
|
420
424
|
</div>
|
|
@@ -436,7 +440,7 @@ coda
|
|
|
436
440
|
coda
|
|
437
441
|
</pre></div>
|
|
438
442
|
</div>
|
|
439
|
-
<div class="p">which would be displayed as:</div><figure><img alt="Method signature" src="spec/signature.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 16. Method signature</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
443
|
+
<div class="p">which would be displayed as:</div><figure><img alt="Method signature" src="spec/signature.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 16. Method signature</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature42">5.3.2. Paragraph</h4><div class="feature-contents"><div class="user-item"><div class="p">A paragraph is described by a string not beginning with <code class="inline">></code>, <code class="inline">*</code>, or <code class="inline">#</code>, and optionally beginning with <code class="inline">!</code> (see <a href="#feature47">5.3.4. Annotation</a> for exceptions). A paragraph is a user item if and only if it does not begin with <code class="inline">!</code>.</div><div class="p">The following markups are applied to a paragraph, with the priority in the order given:</div><ol><li>Locally minimum substring surrounded by balanced sequences of one or more backticks <code class="inline">`...`</code>: inline code</li><li>Substring not including <code class="inline">*</code> surrounded by double asterisks <code class="inline">**...**</code>: bold face</li><li>Substring not including <code class="inline">*</code> surrounded by single asterisks <code class="inline">*...*</code>: italics</li><li>Substring not including <code class="inline">{</code> and <code class="inline">}</code> surrounded by a pair of braces <code class="inline">{...}</code>: link (see <a href="#feature43">5.3.3. Link</a>)</li></ol><div class="p">In order to mark an inline code that includes backticks, surround it with a pair of identical sequences of backticks that are longer than any consecutive backticks in the inline code.</div><div class="p">If an inline code begins and/or ends with a backtick, or if the beginning of a paragraph is to be italicized or bold faced, then insert a space to avoid interference with the notation. Such spaces will be stripped.</div><div class="p">Consecutive space characters in a part of string that is not marked up by any of the above are squeezed into single space characters, so line changes can be made in the middle of a string without affecting the output.</div><div class="p">For example,</div><div class="CodeRay">
|
|
440
444
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">The part `* bar *` in `foo * bar * baz` is not interpreted as an italicized word
|
|
441
445
|
because inline code has precedence over bold face in markup.</span><span class="delimiter">"</span></span>,
|
|
442
446
|
<span class="string"><span class="delimiter">'</span><span class="content">Suppose we have this expression: ``` `echo #{string.sub(/``/, "x")}` ```.
|
|
@@ -449,12 +453,12 @@ coda
|
|
|
449
453
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="char">\u</span><span class="content">25B8</span><span class="delimiter">"</span></span> <span class="comment"># => "▸"</span>
|
|
450
454
|
</pre></div>
|
|
451
455
|
</div>
|
|
452
|
-
<div class="p">Non-marked up portion of a string is also subject to spell checking if the option is turned on (see <a href="#
|
|
456
|
+
<div class="p">Non-marked up portion of a string is also subject to spell checking if the option is turned on (see <a href="#feature22">4.1.1. Spell Check (spell_check, spell-check-list, spell-check-filter, case_sensitive, case_insensitive)</a>).</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature43">5.3.3. Link</h4><div class="feature-contents"><div class="user-item"><div class="p">Links are expressed in a pair of braces <code class="inline">{</code> and <code class="inline">}</code>. No link can have a brace character inside. Depending on the surrounded string, there are three types.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature44">5.3.3.1. External Links</h5><div class="feature-contents"><div class="user-item"><div class="p">An external link is expressed by a string that includes a URL that includes the scheme <code class="inline">://</code>. The URL can optionally be preceded by a link name and a comma <code class="inline">,</code>. The name cannot include <code class="inline">=</code> (This is to avoid ambiguity. See <a href="#feature46">5.3.3.3. Links to Section Headers</a>). This example:</div><div class="CodeRay">
|
|
453
457
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">This is a link without a name: {https://www.ruby-lang.org}, and
|
|
454
458
|
{this, https://www.ruby-lang.org} is a link with a name</span><span class="delimiter">"</span></span>,
|
|
455
459
|
</pre></div>
|
|
456
460
|
</div>
|
|
457
|
-
<div class="p">results in:</div><figure><img alt="External link" src="spec/external_link.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 18. External link</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="
|
|
461
|
+
<div class="p">results in:</div><figure><img alt="External link" src="spec/external_link.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 18. External link</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature45">5.3.3.2. Links to Features</h5><div class="feature-contents"><div class="user-item"><div class="p">A link to a feature is expressed by a string that has a feature name (which starts with <code class="inline">::</code>, <code class="inline">#</code>, or <code class="inline">.</code>), and is optionally preceded by a module. Absence of a module makes the current context/module be the relevant domain. If a module is given, it is interpreted with the same rule as in Ruby code, relative to the current context. The following are possible links:</div><div class="CodeRay">
|
|
458
462
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#a</span><span class="delimiter">"</span></span>,
|
|
459
463
|
<span class="string"><span class="delimiter">"</span><span class="content">Links in each list item have the same target.</span><span class="delimiter">"</span></span>,
|
|
460
464
|
<span class="string"><span class="delimiter">"</span><span class="content">* {#b}, {Object#b}</span><span class="delimiter">"</span></span>,
|
|
@@ -468,7 +472,7 @@ coda
|
|
|
468
472
|
<span class="keyword">end</span>
|
|
469
473
|
</pre></div>
|
|
470
474
|
</div>
|
|
471
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="
|
|
475
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature46">5.3.3.3. Links to Section Headers</h5><div class="feature-contents"><div class="user-item"><div class="p">A link to a section header is expressed by a string that starts with a single <code class="inline">=</code>, followed by the name of the section header, and is optionally preceded by a module.</div><div class="p">Omission of a module makes the link refer to the current context. The main context is described as <code class="inline">::</code>, which has different effect from <code class="inline">Object</code> when linking to section headers, unlike when linking to features (see <a href="#feature39">5.2.4. Main Context</a>). When the link target belongs to a different context from where it is written, the context is described in parentheses. Suppose we have section headers named “Summary” in the main context, the <code class="inline">Object</code> class, and another class <code class="inline">A</code>, and some some links:</div><div class="CodeRay">
|
|
472
476
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">=Summary</span><span class="delimiter">"</span></span>,
|
|
473
477
|
coda
|
|
474
478
|
|
|
@@ -534,7 +538,7 @@ coda
|
|
|
534
538
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">{=Summary}, {=Foo=Summary}, {=Bar=Summary}, {=Bar=Bar=Summary}</span><span class="delimiter">"</span></span>
|
|
535
539
|
</pre></div>
|
|
536
540
|
</div>
|
|
537
|
-
<div class="p">which will be rendered as:</div><figure><img alt="Unambiguous Links" src="spec/unambiguous_links.png" style="width:100%;;border:1px solid hsl(0, 0%, 80%);;" /><figcaption>Figure 21. Unambiguous Links</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
541
|
+
<div class="p">which will be rendered as:</div><figure><img alt="Unambiguous Links" src="spec/unambiguous_links.png" style="width:100%;;border:1px solid hsl(0, 0%, 80%);;" /><figcaption>Figure 21. Unambiguous Links</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature47">5.3.4. Annotation</h4><div class="feature-contents"><div class="user-item"><div class="p">Annotations are not user items.</div><div class="p">A string item in the spec file that starts with with <code class="inline">!!</code> or <code class="inline">!</code>, followed by an optional space, an <span class="italic">annotation tag</span> consisting of non-space characters, and a colon <code class="inline">:</code> is an annotation, particularly a log item (rather than a developer's paragraph). A spec file may look like:</div><div class="CodeRay">
|
|
538
542
|
<div class="code"><pre>manage <span class="string"><span class="delimiter">"</span><span class="content">sample.rb</span><span class="delimiter">"</span></span>
|
|
539
543
|
|
|
540
544
|
spec <span class="predefined-constant">nil</span>,
|
|
@@ -567,7 +571,7 @@ coda
|
|
|
567
571
|
<span class="keyword">end</span>
|
|
568
572
|
</pre></div>
|
|
569
573
|
</div>
|
|
570
|
-
<div class="p">The purpose of a tag is to relate different annotations. Annotations in the same scope with the same tag are concatenated and displayed as one (see <a href="#
|
|
574
|
+
<div class="p">The purpose of a tag is to relate different annotations. Annotations in the same scope with the same tag are concatenated and displayed as one (see <a href="#feature17">3.2.2.3.1. Annotations and Editorial Markings</a>). The number of exclamation marks at the beginning of an annotation expresses the scope:</div><ul><li><code class="inline">#!!</code> in the spec file or <code class="inline">!!</code> in a program code expresses file scope; all annotations with the same tag within the same program file are concatenated together.</li><li><code class="inline">#!</code> in the spec file or <code class="inline">!</code> in a program code expresses method-body scope; all annotations with the same tag within the body of the same method in a program code are concatenated together.</li></ul><div class="p">Running Manager with the spec file above and the program code above (named as <code class="inline">sample.rb</code>) will result in the following (with irrelevant content removed):</div><figure><img alt="Annotations" src="spec/annotations.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 22. Annotations</figcaption></figure><div class="p">An annotation in the spec file with a file-scope tag can only appear in the main context with an implicit or an explicit section header (i.e. not with a constant or a method). The following spec file is invalid.</div><div class="CodeRay">
|
|
571
575
|
<div class="code"><pre>manage <span class="string"><span class="delimiter">"</span><span class="content">sample.rb</span><span class="delimiter">"</span></span>
|
|
572
576
|
|
|
573
577
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
@@ -582,12 +586,12 @@ coda
|
|
|
582
586
|
<span class="keyword">end</span>
|
|
583
587
|
</pre></div>
|
|
584
588
|
</div>
|
|
585
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
589
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature48">5.3.5. Citation</h4><div class="feature-contents"><div class="user-item"><div class="p">Citation is described by a string starting with <code class="inline">></code>. If the string has <code class="inline">!</code> right after it, then it is not a user item, otherwise, it is a user item.</div><div class="CodeRay">
|
|
586
590
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">> This is user citation</span><span class="delimiter">"</span></span>,
|
|
587
591
|
<span class="string"><span class="delimiter">"</span><span class="content">>! This is developer citation</span><span class="delimiter">"</span></span>,
|
|
588
592
|
</pre></div>
|
|
589
593
|
</div>
|
|
590
|
-
<div class="p">These citations are displayed in the developer's chart as:</div><figure><img alt="Citations" src="spec/citation.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 23. Citations</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
594
|
+
<div class="p">These citations are displayed in the developer's chart as:</div><figure><img alt="Citations" src="spec/citation.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 23. Citations</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature49">5.3.6. List</h4><div class="feature-contents"><div class="user-item"><div class="p">A list item is described by a string starting with a sequence of one or more <code class="inline">*</code> or <code class="inline">#</code>. If the string has <code class="inline">!</code> right after it, then it is not a user item, otherwise it is a user item.</div><div class="p">Consecutive list items constitute a list. Each <code class="inline">*</code> or <code class="inline">#</code> at the beginning of an item represents an un-numbered or numbered item respectively at the corresponding level. No other type of items may intervene list items in order for the list items to be recognized as a single list. This is important for lists that have numbered items, as the numbers will be reset by interruption. The following spec file:</div><div class="CodeRay">
|
|
591
595
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content"># user item</span><span class="delimiter">"</span></span>,
|
|
592
596
|
<span class="string"><span class="delimiter">"</span><span class="content">## user item</span><span class="delimiter">"</span></span>,
|
|
593
597
|
<span class="string"><span class="delimiter">"</span><span class="content">##* user item</span><span class="delimiter">"</span></span>,
|
|
@@ -603,7 +607,7 @@ coda
|
|
|
603
607
|
<span class="string"><span class="delimiter">"</span><span class="content">#! developer item</span><span class="delimiter">"</span></span>,
|
|
604
608
|
</pre></div>
|
|
605
609
|
</div>
|
|
606
|
-
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="List" src="spec/list.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 24. List</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
610
|
+
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="List" src="spec/list.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 24. List</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature50">5.3.7. Line</h4><div class="feature-contents"><div class="user-item"><div class="p">A string that starts with one or more consecutive <code class="inline">-</code> describes a line. It can be used to split units that are larger than paragraphs. If it is followed by <code class="inline">!</code>, then it is not a user item. Otherwise, it is a user item.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature51">5.3.8. Code Block</h4><div class="feature-contents"><div class="user-item"><div class="p">A code block is expressed by a string followed by the method <a href="#feature228"><code class="inline">String#code</code></a> or <a href="#feature229"><code class="inline">String#code!</code></a>. These methods take an optional symbol argument in lower case, which describes the programming language in which syntax highlighting takes place (see <a href="#feature29">4.1.8. Syntax Highlighting (highlight, highlight-list)</a>). By default, this is <code class="inline">:ruby</code>. Method <code class="inline">code</code> is for user item, and <code class="inline">code!</code> is for developer item. The recommended practice is to use a here document with an identifier of the form <code class="inline">~'RUBY'</code>.</div><ul><li>The <code class="inline">~</code> un-indents the code block to its least indented level.</li><li>The single quotes <code class="inline">'...'</code> assure verbatim interpretation of the code block.</li><li>A string expressing the language in capital, like <code class="inline">RUBY</code>, is recognized by many text editors so that syntax highlighting inside the code string will be done in that language.</li></ul></div><div class="user-item"><div class="p">The following example:</div><div class="CodeRay">
|
|
607
611
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">A Ruby example for users:</span><span class="delimiter">"</span></span>,
|
|
608
612
|
<span class="string"><span class="delimiter"><<~'RUBY'</span></span>.code,<span class="string"><span class="content">
|
|
609
613
|
def foo
|
|
@@ -618,7 +622,7 @@ RUBY</span></span>
|
|
|
618
622
|
CSS</span></span>
|
|
619
623
|
</pre></div>
|
|
620
624
|
</div>
|
|
621
|
-
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="Code block" src="spec/code_block.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 25. Code block</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
625
|
+
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="Code block" src="spec/code_block.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 25. Code block</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature52">5.3.9. Image</h4><div class="feature-contents"><div class="user-item"><div class="p">An image is expressed by the method <a href="#feature163"><code class="inline">Module#image</code></a> or <a href="#feature164"><code class="inline">Module#image!</code></a>. Method <code class="inline">image</code> is for user item, and <code class="inline">image!</code> is for developer item. These methods take an obligatory string argument expressing the caption, an obligatory string argument describing the path of the image file (either absolute or relative to the output directory; see <a href="#feature23">4.1.2. Output Directory (odir)</a>), and an optional hash of symbol keys and string or numeral values, which will be expanded into CSS commands in the generated HTML files.</div><div class="p">The following example:</div><div class="CodeRay">
|
|
622
626
|
<div class="code"><pre><span class="string"><span class="delimiter">"</span><span class="content">For users</span><span class="delimiter">"</span></span>,
|
|
623
627
|
image(<span class="string"><span class="delimiter">"</span><span class="content">Ruby logo (Copyright © 2006, Yukihiro Matsumoto)</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">ruby.png</span><span class="delimiter">"</span></span>, <span class="key">width</span>: <span class="integer">200</span>),
|
|
624
628
|
<span class="string"><span class="delimiter">"</span><span class="content">! For developers</span><span class="delimiter">"</span></span>,
|
|
@@ -626,14 +630,14 @@ image!(<span class="string"><span class="delimiter">"</span><span class="co
|
|
|
626
630
|
<span class="key">border</span>: <span class="string"><span class="delimiter">"</span><span class="content">1px solid hsl(0, 0%, 80%)</span><span class="delimiter">"</span></span>),
|
|
627
631
|
</pre></div>
|
|
628
632
|
</div>
|
|
629
|
-
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="Image" src="spec/image.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 26. Image</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
633
|
+
<div class="p">is displayed in the developer's chart as:</div><figure><img alt="Image" src="spec/image.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 26. Image</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature53">5.3.10. Table</h4><div class="feature-contents"><div class="user-item"><div class="p">Tables are user items. They are described by an array of arrays, each of which expresses a row, whose elements are strings, each of which expresses a cell.</div><div class="p">Text alignment of each cell is controlled by initial/final spacing in the string. Depending on whether the string has only a final space, only an initial space, or both, the cell will be left aligned, right aligned, or center aligned, respectively. Otherwise, the string will be left aligned by default. This item:</div><div class="CodeRay">
|
|
630
634
|
<div class="code"><pre>[
|
|
631
635
|
[<span class="string"><span class="delimiter">"</span><span class="content"> Right aligned.</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">A very very very very very long cell.</span><span class="delimiter">"</span></span>],
|
|
632
636
|
[<span class="string"><span class="delimiter">"</span><span class="content">Another cell that is quite loooooooooooooooooong.</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content"> This is centered. </span><span class="delimiter">"</span></span>]
|
|
633
637
|
],
|
|
634
638
|
</pre></div>
|
|
635
639
|
</div>
|
|
636
|
-
<div class="p">is rendered as a table like this:</div><figure><img alt="Table" src="spec/table.png" style="border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 27. Table</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="
|
|
640
|
+
<div class="p">is rendered as a table like this:</div><figure><img alt="Table" src="spec/table.png" style="border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 27. Table</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h3 id="feature54">5.4. Testing</h3><div class="feature-contents"><div class="user-item"><div class="p">Manager can perform two types of tests: <span class="italic">unit test</span> and <span class="italic">benchmark</span>.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature55">5.4.1. Unit Test</h4><div class="feature-contents"><div class="user-item"><div class="p">A unit test can be defined by the following steps:</div><ol><li><span class="italic">Setup</span>: Prepare objects and states required for the test. Often described by the term <code class="inline">Given</code> in conventional test frameworks.</li><li><span class="italic">Exercise</span>: Perform the behavior that is the object of test. Often described by <code class="inline">When</code>.</li><li><span class="italic">Verification</span>: Check the result of exercise. Often described by <code class="inline">Then</code>.</li><li>Additional verification: In required, do more checks on the result or on any change that is caused by the exercise. Often described by <code class="inline">And</code> after <code class="inline">Then</code>.</li></ol><div class="p">In unit test in Manager, each step is described in the following way:</div><ol><li>Setup: Describe the objects using Ruby literal expressions, or using <a href="#feature227"><code class="inline">String#setup</code></a> and <a href="#feature116"><code class="inline">::#expr</code></a> methods (see <a href="#feature59">5.4.4. The `expr` Method</a>, <a href="#feature60">5.4.5. Setup and Teardown</a>).</li><li>Exercise: Describe the Ruby expression that should be performed using the objects prepared by setup, but substitute the relevant feature (method or constant) call with the placeholder <a href="#feature154"><code class="inline">BasicObject#UT</code></a>.</li><li>Verification: After the exercise, chain method call(s) that should be evaluated to a truthy value. (For this step, a methods named <code class="inline">initialize</code> and <code class="inline">method_missing</code> cannot be used. But this should rarely be a problem.)</li><li>Additional verification: Describe in a similar way as verification, but substitute the return value of exercise and the original receiver of exercise with the placeholders <code class="inline">RETURN</code> and <code class="inline">RECEIVER</code>, respectively.</li></ol><div class="p">Every time <code class="inline">UT</code> is called, the value of <code class="inline">RETURN</code> and <code class="inline">RECEIVER</code> are reset.</div><div class="p">The following is an example of testing the <code class="inline">Array#push</code> method.</div><div class="CodeRay">
|
|
637
641
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">Array</span>
|
|
638
642
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#push</span><span class="delimiter">"</span></span>,
|
|
639
643
|
[].UT(<span class="string"><span class="delimiter">"</span><span class="content">a</span><span class="delimiter">"</span></span>) == [<span class="string"><span class="delimiter">"</span><span class="content">a</span><span class="delimiter">"</span></span>],
|
|
@@ -656,7 +660,7 @@ image!(<span class="string"><span class="delimiter">"</span><span class="co
|
|
|
656
660
|
<span class="keyword">end</span>
|
|
657
661
|
</pre></div>
|
|
658
662
|
</div>
|
|
659
|
-
<figure><img alt="Unit test failed" src="spec/unit_test_failure.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 29. Unit test failed</figcaption></figure><div class="p">After the first exercise is reported as resulting in a bug, the two verifications following (using <code class="inline">RETURN</code> and <code class="inline">RECEIVER</code>) are reported as untestable. They are reported as success or bug only when there is a preceding exercise that has succeeded. There are some other possibilities for the result of a unit test. See <a href="#
|
|
663
|
+
<figure><img alt="Unit test failed" src="spec/unit_test_failure.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 29. Unit test failed</figcaption></figure><div class="p">After the first exercise is reported as resulting in a bug, the two verifications following (using <code class="inline">RETURN</code> and <code class="inline">RECEIVER</code>) are reported as untestable. They are reported as success or bug only when there is a preceding exercise that has succeeded. There are some other possibilities for the result of a unit test. See <a href="#feature18">3.2.2.4. Test Reports</a> for detail.</div><div class="p">In order to repeat the same test schema over data, a tip is to use <code class="inline">map</code> with splat <code class="inline">*</code>.</div><div class="CodeRay">
|
|
660
664
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
661
665
|
*[
|
|
662
666
|
[<span class="string"><span class="delimiter">"</span><span class="content">a</span><span class="delimiter">"</span></span>, <span class="integer">1</span>],
|
|
@@ -666,7 +670,7 @@ image!(<span class="string"><span class="delimiter">"</span><span class="co
|
|
|
666
670
|
coda
|
|
667
671
|
</pre></div>
|
|
668
672
|
</div>
|
|
669
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="
|
|
673
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h5 id="feature56">5.4.1.1. Testing with <code class="inline">succeed?</code>, <code class="inline">raise?</code>, and <code class="inline">throw?</code></h5><div class="feature-contents"><div class="user-item"><div class="p">Sometimes, it is necessary to only verify that examination was performed without raising an exception. In such cases, use the method <code class="inline">succeed?</code>. Tests using this method will report success whenever examination was performed without an exception, without particular verification on the return value.</div><div class="CodeRay">
|
|
670
674
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
671
675
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#concat</span><span class="delimiter">"</span></span>,
|
|
672
676
|
<span class="string"><span class="delimiter">"</span><span class="delimiter">"</span></span>.UT(<span class="symbol">:a</span>).succeed?,
|
|
@@ -708,7 +712,7 @@ coda
|
|
|
708
712
|
coda
|
|
709
713
|
</pre></div>
|
|
710
714
|
</div>
|
|
711
|
-
<figure><img alt="Unit test expecting throwing" src="spec/unit_test_throw.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 33. Unit test expecting throwing</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
715
|
+
<figure><img alt="Unit test expecting throwing" src="spec/unit_test_throw.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 33. Unit test expecting throwing</figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature57">5.4.2. Benchmark</h4><div class="feature-contents"><div class="user-item"><div class="p">Benchmark is described similarly to unit test, but it only has the setup and exercise steps. For the exercise step, use the placeholder <a href="#feature155"><code class="inline">BasicObject#BM</code></a>. Benchmark is meaningful only when there are alternative implementations for the method in question (see <a href="#feature15">3.2.2.2. Alternative Implementations</a>). Suppose the following three alternative implementations are examined for a feature that parses an integer from a string:</div><div class="CodeRay">
|
|
712
716
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
713
717
|
<span class="keyword">def</span> <span class="function">check_int__1</span>
|
|
714
718
|
Integer(<span class="predefined-constant">self</span>) <span class="keyword">rescue</span> <span class="predefined-constant">false</span>
|
|
@@ -731,7 +735,7 @@ coda
|
|
|
731
735
|
<span class="keyword">end</span>
|
|
732
736
|
</pre></div>
|
|
733
737
|
</div>
|
|
734
|
-
<div class="p">can have a result like:</div><figure><img alt="Benchmark test" src="spec/benchmark_test.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 34. Benchmark test</figcaption></figure><div class="p">Based on the result, one may discuss that <code class="inline">check_int__1</code> performs the best with string expressing valid integers like <code class="inline">"220000"</code>, but its performance is not stable, as can be seen in the slowness with invalid strings like <code class="inline">"22.to.2"</code>.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
738
|
+
<div class="p">can have a result like:</div><figure><img alt="Benchmark test" src="spec/benchmark_test.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 34. Benchmark test</figcaption></figure><div class="p">Based on the result, one may discuss that <code class="inline">check_int__1</code> performs the best with string expressing valid integers like <code class="inline">"220000"</code>, but its performance is not stable, as can be seen in the slowness with invalid strings like <code class="inline">"22.to.2"</code>.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature58">5.4.3. Test Header</h4><div class="feature-contents"><div class="user-item"><div class="p">Test items can be grouped into a hierarchy, numbered, and named using <span class="italic">test headers</span>. A test header is described as a string that starts with one or more question mark characters <code class="inline">?</code>. Each header is numbered at the depth represented by the number of <code class="inline">?</code> characters at the beginning. Examples are shown below:</div><div class="CodeRay">
|
|
735
739
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
736
740
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#capitalize!</span><span class="delimiter">"</span></span>,
|
|
737
741
|
<span class="string"><span class="delimiter">"</span><span class="content">? When `self` is not capitalized, it should return the capitalized string.</span><span class="delimiter">"</span></span>,
|
|
@@ -745,7 +749,7 @@ coda
|
|
|
745
749
|
<span class="keyword">end</span>
|
|
746
750
|
</pre></div>
|
|
747
751
|
</div>
|
|
748
|
-
<div class="p">The result may be displayed as follows:</div><figure><img alt="Test header" src="spec/test_header.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 35. Test header</figcaption></figure><div class="p">In future versions of Manager, test header is planned to play a role in doing test setups in hierarchy (cf. nested setup syntax in conventional test frameworks), but its specification is not decided yet. Feedback is welcome.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
752
|
+
<div class="p">The result may be displayed as follows:</div><figure><img alt="Test header" src="spec/test_header.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 35. Test header</figcaption></figure><div class="p">In future versions of Manager, test header is planned to play a role in doing test setups in hierarchy (cf. nested setup syntax in conventional test frameworks), but its specification is not decided yet. Feedback is welcome.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature59">5.4.4. The <code class="inline">expr</code> Method</h4><div class="feature-contents"><div class="user-item"><div class="p">Besides being directly described as objects, the receiver and arguments of tests can be described using the method <a href="#feature116"><code class="inline">Object#expr</code></a>, which takes a string argument. The string is evaluated at the timing of the relevant test step. The <code class="inline">expr</code> method has three purposes:</div><ol><li>Reset the object in case performing the tests modifies the objects involved</li><li>Control the inspection form that is displayed in the test reports</li><li>Refer to objects in the context of the test (such as is defined in a setup, see <a href="#feature60">5.4.5. Setup and Teardown</a>)</li></ol><div class="p">As an example of the first purpose, suppose some alternative implementations of a destructive method are defined:</div><div class="CodeRay">
|
|
749
753
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">Array</span>
|
|
750
754
|
<span class="keyword">def</span> <span class="function">push_a</span>
|
|
751
755
|
push(<span class="string"><span class="delimiter">"</span><span class="content">a</span><span class="delimiter">"</span></span>)
|
|
@@ -812,7 +816,7 @@ expr(<span class="string"><span class="delimiter">"</span><span class="cont
|
|
|
812
816
|
expr(<span class="string"><span class="delimiter">"</span><span class="content">Array.new(1000){</span><span class="char">\"</span><span class="content">a</span><span class="char">\"</span><span class="content">} + Array.new(1000){</span><span class="char">\"</span><span class="content">b</span><span class="char">\"</span><span class="content">}</span><span class="delimiter">"</span></span>),
|
|
813
817
|
</pre></div>
|
|
814
818
|
</div>
|
|
815
|
-
<div class="p">would make the displayed result shorter and understandable. The parts of the expression using <code class="inline">expr</code> are displayed in the form of the string passed:</div><figure><img alt="Display made short with `expr`" src="spec/short.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 39. Display made short with <code class="inline">expr</code></figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="
|
|
819
|
+
<div class="p">would make the displayed result shorter and understandable. The parts of the expression using <code class="inline">expr</code> are displayed in the form of the string passed:</div><figure><img alt="Display made short with `expr`" src="spec/short.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 39. Display made short with <code class="inline">expr</code></figcaption></figure></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h4 id="feature60">5.4.5. Setup and Teardown</h4><div class="feature-contents"><div class="user-item"><div class="p">The third purpose of using <code class="inline">expr</code> in tests is to refer to variables and methods that have been set up in advance. A setup can be described as a string followed by the <a href="#feature227"><code class="inline">String#setup</code></a> method. The recommended way is to write this as a here document, as with code blocks (<a href="#feature51">5.3.8. Code Block</a>). Setups are accumulated over the spec file, and is evaluated for each exercise step in a test. The <a href="#feature165"><code class="inline">Module#teardown</code></a> item will reset all preceding setups. Following is an example of using these methods.</div><div class="CodeRay">
|
|
816
820
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">Array</span>
|
|
817
821
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#flatten!</span><span class="delimiter">"</span></span>,
|
|
818
822
|
<span class="string"><span class="delimiter"><<~'RUBY'</span></span>.setup,<span class="string"><span class="content">
|
|
@@ -834,7 +838,7 @@ expr(<span class="string"><span class="delimiter">"</span><span class="cont
|
|
|
834
838
|
<span class="keyword">end</span>
|
|
835
839
|
</pre></div>
|
|
836
840
|
</div>
|
|
837
|
-
<div class="p">This will result in the following:</div><figure><img alt="Setup and teardown" src="spec/setup_teardown.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 40. Setup and teardown</figcaption></figure><div class="p">Any changes made by <code class="inline">setup</code> to global variables are not reset by <code class="inline">teardown</code>, and needs to be undone manually. Not doing so properly can result in Manager not running correctly.</div><div class="p">In future versions of Manager, test setups are planned to be more structured, i.e. in hierarchy as in nested setup syntax in conventional test frameworks, but its specification is not decided yet. Feedback is welcome.</div></div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
841
|
+
<div class="p">This will result in the following:</div><figure><img alt="Setup and teardown" src="spec/setup_teardown.png" style="width:100%;border:1px solid hsl(0, 0%, 80%);" /><figcaption>Figure 40. Setup and teardown</figcaption></figure><div class="p">Any changes made by <code class="inline">setup</code> to global variables are not reset by <code class="inline">teardown</code>, and needs to be undone manually. Not doing so properly can result in Manager not running correctly.</div><div class="p">In future versions of Manager, test setups are planned to be more structured, i.e. in hierarchy as in nested setup syntax in conventional test frameworks, but its specification is not decided yet. Feedback is welcome.</div></div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature61"><span class="anchor" id="public1"><span class="tag public">public</span></span> class <span class="feature-name">Manager</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature69"><span class="anchor" id="public2"><span class="tag public">public</span></span> <span class="anchor" id="singleton1"><span class="tag singleton">1</span></span> Manager.<span class="feature-name">config</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(symbol)</code> → Object<div class="p">Gets the Manager configuration. <code class="inline">symbol</code> can take the following values. See <a href="#feature21">(main) 4.1. Customization and Options</a> for detail.</div><ul><li><code class="inline">:bdir</code></li><li><code class="inline">:odir</code></li><li><code class="inline">:user</code></li><li><code class="inline">:dev</code></li><li><code class="inline">:theme</code></li><li><code class="inline">:highlight</code></li><li><code class="inline">:debug</code></li><li><code class="inline">:spell_check</code></li><li><code class="inline">:case_sensitive</code></li><li><code class="inline">:case_insensitive</code></li><li><code class="inline">:title</code></li></ul><div class="CodeRay">
|
|
838
842
|
<div class="code"><pre><span class="constant">Manager</span>.config(<span class="symbol">:odir</span>)
|
|
839
843
|
</pre></div>
|
|
840
844
|
</div>
|
|
@@ -842,11 +846,11 @@ expr(<span class="string"><span class="delimiter">"</span><span class="cont
|
|
|
842
846
|
<div class="code"><pre><span class="constant">Manager</span>.config(<span class="key">odir</span>: <span class="string"><span class="delimiter">"</span><span class="content">../</span><span class="delimiter">"</span></span>, <span class="key">title</span>: <span class="string"><span class="delimiter">"</span><span class="content">My Special Program</span><span class="delimiter">"</span></span>, <span class="key">spell_check</span>: <span class="string"><span class="delimiter">"</span><span class="content">en</span><span class="delimiter">"</span></span>)
|
|
843
847
|
</pre></div>
|
|
844
848
|
</div>
|
|
845
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
849
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature81"><span class="anchor" id="public3"><span class="tag public">public</span></span> <span class="anchor" id="singleton2"><span class="tag singleton">2</span></span> Manager.<span class="feature-name">new</span></h2><div class="feature-contents"><div class="user-item"><div class="p">The main method to be called when running Manager. See <a href="#feature20">(main) 4. Running Manager</a>.</div><span class="head">Usage</span> <code class="inline">(file, **command_options)</code> → <code class="inline">nil</code><div class="p">The <code class="inline">file</code> argument is a string expressing the path to the spec file. <code class="inline">command_options</code> are options as explained in <a href="#feature21">(main) 4.1. Customization and Options</a>.</div><div class="CodeRay">
|
|
846
850
|
<div class="code"><pre><span class="constant">Manager</span>.new(<span class="string"><span class="delimiter">"</span><span class="content">../spec_file.rb</span><span class="delimiter">"</span></span>, <span class="key">bdir</span>: <span class="string"><span class="delimiter">"</span><span class="content">../</span><span class="delimiter">"</span></span>)
|
|
847
851
|
</pre></div>
|
|
848
852
|
</div>
|
|
849
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
853
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature115"><span class="anchor" id="public4"><span class="tag public">public</span></span> class <span class="feature-name">Object</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature116"><span class="anchor" id="private1"><span class="tag private">private</span></span> <span class="anchor" id="instance1"><span class="tag instance">1</span></span> Object#<span class="feature-name">expr</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(string)</code> → Manager::Expr<div class="p">Wraps a expression (string). Its content is evaluated during tests. Its inspected form is the original string expression, not the inspection form of the object it represents.</div><div class="CodeRay">
|
|
850
854
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
851
855
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#upcase</span><span class="delimiter">"</span></span>,
|
|
852
856
|
<span class="string"><span class="delimiter">"</span><span class="content">long_foo = </span><span class="char">\"</span><span class="content">foo</span><span class="char">\"</span><span class="content"> * 100</span><span class="delimiter">"</span></span>.setup,
|
|
@@ -855,21 +859,21 @@ expr(<span class="string"><span class="delimiter">"</span><span class="cont
|
|
|
855
859
|
<span class="keyword">end</span>
|
|
856
860
|
</pre></div>
|
|
857
861
|
</div>
|
|
858
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
862
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature117"><span class="anchor" id="public5"><span class="tag public">public</span></span> <span class="anchor" id="instance2"><span class="tag instance">2</span></span> Object#<span class="feature-name">in?</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(array)</code> → <code class="inline">true</code> | <code class="inline">false</code><div class="p">A helper method for writing tests. It switches the receiver and the argument of <code class="inline">Array#include?</code>.</div><div class="CodeRay">
|
|
859
863
|
<div class="code"><pre><span class="integer">1</span>.in?([<span class="integer">1</span>, <span class="integer">2</span>]) <span class="comment">#=> true</span>
|
|
860
864
|
<span class="integer">3</span>.in?([<span class="integer">1</span>, <span class="integer">2</span>]) <span class="comment">#=> false</span>
|
|
861
865
|
</pre></div>
|
|
862
866
|
</div>
|
|
863
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
867
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature150"><span class="anchor" id="public6"><span class="tag public">public</span></span> class <span class="feature-name"><< main</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature151"><span class="anchor" id="public7"><span class="tag public">public</span></span> <span class="anchor" id="instance3"><span class="tag instance">3</span></span> << main#<span class="feature-name">gemspec</span></h2><div class="feature-contents"><div class="user-item"><div class="p">When the program under analysis is a Ruby gem, and this method is called, the gem spec information is displayed in the left panel of developer's chart.</div><span class="head">Usage</span> <code class="inline">(file)</code> → Gem::Specification<div class="p"><code class="inline">file</code> should be the path to the <code class="inline">.gemspec</code> file either absolute or relative to the spec file.</div><div class="CodeRay">
|
|
864
868
|
<div class="code"><pre>gemspec <span class="string"><span class="delimiter">"</span><span class="content">../manager.gemspec</span><span class="delimiter">"</span></span>
|
|
865
869
|
</pre></div>
|
|
866
870
|
</div>
|
|
867
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
871
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature152"><span class="anchor" id="public8"><span class="tag public">public</span></span> <span class="anchor" id="instance4"><span class="tag instance">4</span></span> << main#<span class="feature-name">manage</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Registers the files to be analyzed. Files that are loaded or required other than by method would not be the object of analysis.</div><span class="head">Usage</span> <code class="inline">(file)</code> → <code class="inline">nil</code><div class="p"><code class="inline">file</code> should be the path to the <code class="inline">.gemspec</code> file either absolute or relative to the spec file.</div><div class="CodeRay">
|
|
868
872
|
<div class="code"><pre>manage <span class="string"><span class="delimiter">"</span><span class="content">../lib/helpers/foo.rb</span><span class="delimiter">"</span></span>
|
|
869
873
|
manage <span class="string"><span class="delimiter">"</span><span class="content">../lib/helpers/bar.rb</span><span class="delimiter">"</span></span>
|
|
870
874
|
</pre></div>
|
|
871
875
|
</div>
|
|
872
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
876
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature153"><span class="anchor" id="public9"><span class="tag public">public</span></span> class <span class="feature-name">BasicObject</span></h1><div class="feature-contents"><div class="user-item"><div class="p">Besides, <code class="inline">UT</code> and <code class="inline">BM</code> explained below, <code class="inline">RETURN</code> and <code class="inline">RECEIVER</code> can be used in tests.</div></div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature154"><span class="anchor" id="public10"><span class="tag public">public</span></span> <span class="anchor" id="instance5"><span class="tag instance">5</span></span> BasicObject#<span class="feature-name">UT</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(*args, **kargs, &pr)</code> → <code class="inline">Manager::UnitTest</code><div class="p">A placeholder for the feature (method or constant) examined in unit tests.</div><div class="CodeRay">
|
|
873
877
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
874
878
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#capitalize</span><span class="delimiter">"</span></span>,
|
|
875
879
|
<span class="string"><span class="delimiter">"</span><span class="content">foo</span><span class="delimiter">"</span></span>.UT == <span class="string"><span class="delimiter">"</span><span class="content">Foo</span><span class="delimiter">"</span></span>,
|
|
@@ -877,7 +881,7 @@ manage <span class="string"><span class="delimiter">"</span><span class="co
|
|
|
877
881
|
<span class="keyword">end</span>
|
|
878
882
|
</pre></div>
|
|
879
883
|
</div>
|
|
880
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
884
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature155"><span class="anchor" id="public11"><span class="tag public">public</span></span> <span class="anchor" id="instance6"><span class="tag instance">6</span></span> BasicObject#<span class="feature-name">BM</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(*args, **kargs, &pr)</code> → Manager::Benchmark<div class="p">A placeholder for the feature (method or constant) examined in benchmark tests.</div><div class="CodeRay">
|
|
881
885
|
<div class="code"><pre><span class="keyword">class</span> <span class="class">String</span>
|
|
882
886
|
spec <span class="string"><span class="delimiter">"</span><span class="content">#capitalize</span><span class="delimiter">"</span></span>,
|
|
883
887
|
<span class="string"><span class="delimiter">"</span><span class="content">foo</span><span class="delimiter">"</span></span>.BM,
|
|
@@ -885,59 +889,59 @@ manage <span class="string"><span class="delimiter">"</span><span class="co
|
|
|
885
889
|
<span class="keyword">end</span>
|
|
886
890
|
</pre></div>
|
|
887
891
|
</div>
|
|
888
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
892
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature156"><span class="anchor" id="public12"><span class="tag public">public</span></span> class <span class="feature-name">Module</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature157"><span class="anchor" id="public13"><span class="tag public">public</span></span> <span class="anchor" id="instance7"><span class="tag instance">7</span></span> Module#<span class="feature-name">hide</span></h2><div class="feature-contents"><div class="user-item"><div class="p">When a <code class="inline">spec</code> method is prefixed with this method, the specification will be hided in the user' manual.</div><span class="head">Usage</span> <code class="inline">()</code> → <div class="CodeRay">
|
|
889
893
|
<div class="code"><pre>hide spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
890
894
|
...
|
|
891
895
|
coda
|
|
892
896
|
</pre></div>
|
|
893
897
|
</div>
|
|
894
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
898
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature158"><span class="anchor" id="public14"><span class="tag public">public</span></span> <span class="anchor" id="instance8"><span class="tag instance">8</span></span> Module#<span class="feature-name">move</span></h2><div class="feature-contents"><div class="user-item"><div class="p">When a <code class="inline">spec</code> method is prefixed with this method, the specification will be immune to the misplaced warning.</div><span class="head">Usage</span> <code class="inline">()</code> → <div class="CodeRay">
|
|
895
899
|
<div class="code"><pre>move spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
896
900
|
...
|
|
897
901
|
coda
|
|
898
902
|
</pre></div>
|
|
899
903
|
</div>
|
|
900
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
904
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature159"><span class="anchor" id="public15"><span class="tag public">public</span></span> <span class="anchor" id="instance9"><span class="tag instance">9</span></span> Module#<span class="feature-name">spec</span></h2><div class="feature-contents"><div class="user-item"><div class="p">The main method to describe a specification.</div><span class="head">Usage</span> <code class="inline">(feature, *[items])</code> → <code class="inline">nil</code><div class="CodeRay">
|
|
901
905
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
902
906
|
...
|
|
903
907
|
coda
|
|
904
908
|
</pre></div>
|
|
905
909
|
</div>
|
|
906
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
910
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature160"><span class="anchor" id="public16"><span class="tag public">public</span></span> <span class="anchor" id="instance10"><span class="tag instance">10</span></span> Module#<span class="feature-name">coda</span></h2><div class="feature-contents"><div class="user-item"><div class="p">A pseudo-keyword to close the block opened by the <code class="inline">spec</code> method.</div><span class="head">Usage</span> <code class="inline">()</code> → Manager::Coda<div class="CodeRay">
|
|
907
911
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
908
912
|
...
|
|
909
913
|
coda
|
|
910
914
|
</pre></div>
|
|
911
915
|
</div>
|
|
912
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
916
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature161"><span class="anchor" id="public17"><span class="tag public">public</span></span> <span class="anchor" id="instance11"><span class="tag instance">11</span></span> Module#<span class="feature-name">value</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Wraps an individual object in a method signature.</div><span class="head">Usage</span> <code class="inline">(object)</code> → Module<div class="CodeRay">
|
|
913
917
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
914
918
|
{<span class="string"><span class="delimiter">"</span><span class="content">(string, array)</span><span class="delimiter">"</span></span> => <span class="constant">String</span> | value(<span class="predefined-constant">nil</span>)},
|
|
915
919
|
...
|
|
916
920
|
coda
|
|
917
921
|
</pre></div>
|
|
918
922
|
</div>
|
|
919
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
923
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature162"><span class="anchor" id="public18"><span class="tag public">public</span></span> <span class="anchor" id="instance12"><span class="tag instance">12</span></span> Module#<span class="feature-name">error</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Wraps an exception class in a method signature.</div><span class="head">Usage</span> <code class="inline">(exception, **message: nil)</code> → Module<div class="CodeRay">
|
|
920
924
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
921
925
|
{<span class="string"><span class="delimiter">"</span><span class="content">(string, array)</span><span class="delimiter">"</span></span> => <span class="constant">String</span> | error(<span class="constant">ArgumentError</span>)},
|
|
922
926
|
...
|
|
923
927
|
coda
|
|
924
928
|
</pre></div>
|
|
925
929
|
</div>
|
|
926
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
930
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature163"><span class="anchor" id="public19"><span class="tag public">public</span></span> <span class="anchor" id="instance13"><span class="tag instance">13</span></span> Module#<span class="feature-name">image</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Describe an image for the user's manual.</div><span class="head">Usage</span> <code class="inline">(title, path)</code> → Manager::Render::Image<div class="CodeRay">
|
|
927
931
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
928
932
|
image(<span class="string"><span class="delimiter">"</span><span class="content">Initial diagram</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">asset/initial_diagram.png</span><span class="delimiter">"</span></span>),
|
|
929
933
|
...
|
|
930
934
|
coda
|
|
931
935
|
</pre></div>
|
|
932
936
|
</div>
|
|
933
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
937
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature164"><span class="anchor" id="public20"><span class="tag public">public</span></span> <span class="anchor" id="instance14"><span class="tag instance">14</span></span> Module#<span class="feature-name">image!</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Describe an image for the developer's chart.</div><span class="head">Usage</span> <code class="inline">(title, path)</code> → Manager::Render::Image<div class="CodeRay">
|
|
934
938
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
935
939
|
image!(<span class="string"><span class="delimiter">"</span><span class="content">Initial diagram</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">asset/initial_diagram.png</span><span class="delimiter">"</span></span>),
|
|
936
940
|
...
|
|
937
941
|
coda
|
|
938
942
|
</pre></div>
|
|
939
943
|
</div>
|
|
940
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
944
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature165"><span class="anchor" id="public21"><span class="tag public">public</span></span> <span class="anchor" id="instance15"><span class="tag instance">15</span></span> Module#<span class="feature-name">teardown</span></h2><div class="feature-contents"><div class="user-item"><div class="p">Resets the effect of all previous setups.</div><span class="head">Usage</span> <code class="inline">()</code> → <div class="CodeRay">
|
|
941
945
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
942
946
|
<span class="string"><span class="delimiter">"</span><span class="content">a = 3</span><span class="delimiter">"</span></span>.setup,
|
|
943
947
|
...
|
|
@@ -945,14 +949,14 @@ coda
|
|
|
945
949
|
coda
|
|
946
950
|
</pre></div>
|
|
947
951
|
</div>
|
|
948
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
952
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature166"><span class="anchor" id="public22"><span class="tag public">public</span></span> class <span class="feature-name">Class</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature167"><span class="anchor" id="public23"><span class="tag public">public</span></span> <span class="anchor" id="instance16"><span class="tag instance">16</span></span> Class#<span class="feature-name">|</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(other)</code> → Manager::MethodSignatureAlternatives<div class="p">Expresses alternatives in the output of method signatures.</div><div class="CodeRay">
|
|
949
953
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
950
954
|
{<span class="string"><span class="delimiter">"</span><span class="content">(string, array)</span><span class="delimiter">"</span></span> => <span class="constant">String</span> | error(<span class="constant">ArgumentError</span>) | value(<span class="predefined-constant">nil</span>)},
|
|
951
955
|
...
|
|
952
956
|
coda
|
|
953
957
|
</pre></div>
|
|
954
958
|
</div>
|
|
955
|
-
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="
|
|
959
|
+
</div></div></div></div><div class="module"><div class="feature" onclick="toggleModuleContents(this)"><h1 class="module-header" id="feature226"><span class="anchor" id="public24"><span class="tag public">public</span></span> class <span class="feature-name">String</span></h1><div class="feature-contents"></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature227"><span class="anchor" id="public25"><span class="tag public">public</span></span> <span class="anchor" id="instance17"><span class="tag instance">17</span></span> String#<span class="feature-name">setup</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">()</code> → Manager::Setup<div class="p">Describes a setup to be used in tests.</div><div class="CodeRay">
|
|
956
960
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
957
961
|
<span class="string"><span class="delimiter"><<~'RUBY'</span></span>.setup,<span class="string"><span class="content">
|
|
958
962
|
a = []
|
|
@@ -962,7 +966,7 @@ coda
|
|
|
962
966
|
coda
|
|
963
967
|
</pre></div>
|
|
964
968
|
</div>
|
|
965
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
969
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature228"><span class="anchor" id="public26"><span class="tag public">public</span></span> <span class="anchor" id="instance18"><span class="tag instance">18</span></span> String#<span class="feature-name">code</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(*language)</code> → Manager::Render::Code<div class="p">Describes a code block for the user's manual. The optional <code class="inline">language</code> argument determines the language to be used in highlighting. By default, it is <code class="inline">:ruby</code>.</div><div class="CodeRay">
|
|
966
970
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
967
971
|
<span class="string"><span class="delimiter"><<~'RUBY'</span></span>.code,<span class="string"><span class="content">
|
|
968
972
|
def foo
|
|
@@ -977,7 +981,7 @@ coda
|
|
|
977
981
|
coda
|
|
978
982
|
</pre></div>
|
|
979
983
|
</div>
|
|
980
|
-
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="
|
|
984
|
+
</div></div></div><div class="feature" onclick="toggleFeatureContents(this)"><h2 id="feature229"><span class="anchor" id="public27"><span class="tag public">public</span></span> <span class="anchor" id="instance19"><span class="tag instance">19</span></span> String#<span class="feature-name">code!</span></h2><div class="feature-contents"><div class="user-item"><span class="head">Usage</span> <code class="inline">(*language)</code> → Manager::Render::Code<div class="p">Describes a code block for the developer's chart. The optional <code class="inline">language</code> argument determines the language to be used in highlighting. By default, it is <code class="inline">:ruby</code>.</div><div class="CodeRay">
|
|
981
985
|
<div class="code"><pre>spec <span class="string"><span class="delimiter">"</span><span class="content">#foo</span><span class="delimiter">"</span></span>,
|
|
982
986
|
<span class="string"><span class="delimiter"><<~'RUBY'</span></span>.code!,<span class="string"><span class="content">
|
|
983
987
|
def foo
|