-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathfile.UI.html
484 lines (386 loc) · 19.8 KB
/
file.UI.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
<!DOCTYPE html>
<html>
<head>
<meta charset='UTF-8'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, user-scalable=no'>
<meta name='apple-touch-fullscreen' content='yes'>
<meta name='apple-mobile-web-app-capable' content='yes'>
<meta name='apple-mobile-web-app-status-bar-style' content='rgba(228,228,228,1.0)'>
<title>YardT2 UI Guide</title>
<link rel='stylesheet' type='text/css' href='css/y_fonts.css' />
<link rel='stylesheet' type='text/css' href='css/highlight.github.css' />
<link rel='stylesheet' type='text/css' href='css/y_style.css' />
<link rel='stylesheet' type='text/css' href='css/y_list.css' />
<link rel='stylesheet' type='text/css' href='css/y_color.css' />
<link rel='stylesheet' type='text/css' href='css/custom.css' />
<link rel='stylesheet' type='text/css' href='css/common.css' />
<script type='text/javascript'>
var pathId = "UI",
relpath = '';
var t2Info = {
CSEP: '.',
ISEP: '#',
NSEP: '::'
};
</script>
<script type='text/javascript' charset='utf-8' src='js/highlight.pack.js'></script>
<script type='text/javascript' charset='utf-8' src='js/y_app.js'></script>
</head>
<body>
<svg id='y_wait' class viewBox='0 0 90 90'></svg>
<div id='settings' class='hidden'></div>
<div id='y_list' class='d h'>
<header id='list_header'></header>
<nav id= 'list_nav' class='y_nav l_nav'>
<ul id='list_items'></ul>
</nav>
</div>
<div id='y_toc' class='f h'>
<header id='toc_header'></header>
<nav id= 'toc_nav' class='y_nav t_nav'>
<ol id='toc_items'></ol>
</nav>
</div>
<div id='y_main' tabindex='-1'>
<header id='y_header'>
<div id='y_menu'>
<a href='/'>Home</a> »
<a href='_index.html'>Index</a> »
<span class='title'><a id='t2_doc_top' href='#'>YardT2 UI Guide ▲</a></span>
</div>
<a id='list_href' href="file_list.html"></a>
<div id='y_measure_em' class='y_measure'></div>
<div id='y_measure_vh' class='y_measure'></div>
<span id='y_measure_50pre' class='y_measure'><code>123456789_123456789_123456789_123456789_123456789_</code></span>
</header>
<div id='content' class='file'>
<h1>YardT2 User Interface Guide</h1>
<h2>Introduction</h2>
<p>A few years ago, I was using <a href="http://yardoc.org/">YARD</a> to doc my own code, using a few <a href="https://github.com/rdoc/rdoc">RDoc</a>
based sites as Ruby references, and using some Ruby reference books. Well, I wore the
books out, was frustrated when using a tablet, and wished for changes in both YARD
& RDoc. So, I started working with YARD, which led to the development of YardT2.</p>
<h2>Window Layout</h2>
<p>The YardT2 window is composed of three panes and a navigation control header.
All three panes are independently scrollable, but will also scroll based on object selection.</p>
<p><img src="assets/yard-t2_all.png" alt="All"></p>
<ul>
<li><strong>Main document pane</strong> (MAIN) - this pane shows the class/module documentation,
other documents (md, rdoc, txt, html, etc) included in the library, and the index
page.</li>
<li><strong>'List' pane</strong> (LIST) - This is similar to the YARD and RDoc panes. It shows
lists of the library classes/modules, methods, and separate documents. It may
also show exceptions, constants and/or other collections/lists.</li>
<li><strong>'Table of Contents' pane</strong> (TOC) - This pane is generated by javascript on the
client, and shows a summary of the current MAIN pane document.</li>
<li><strong>Header</strong> (HDR) - this area (above the main document), has a menu for navigating
up the namespace of the MAIN pane object, buttons for the visibility of the LIST
and TOC panes, a button for opening / closing all source code listings in the
current document, and a button for the settings window.</li>
</ul>
<p>The LIST & TOC panes can each be left docked, hidden, or floated individually on
the right side.
Browser window width determines the layout.</p>
<ul>
<li>Narrow - will not allow the LIST or TOC panes to be docked</li>
<li>Medium - will allow only one pane to be docked</li>
<li>Wide - allows both panes to be docked</li>
</ul>
<p>Typically, a full screen PC browser will render as wide, a tablet in landscape will
render as medium, and a tablet in portrait will render as narrow. The above image
shows a 'wide' layout from a PC.</p>
<p>Note that when using a tablet in landscape, if one hides (or floats) both the LIST
and TOC panes, the font will enlarge such that source code listings will be a bit
over 80 characters wide.</p>
<h2>Header Navigation and Controls</h2>
<p><img src="assets/yard-t2_hdr.png" alt="Header"></p>
<p>The top left has navigation items for the nesting of the current document. The
last item is the current document, clicking it will scroll to the top of the document.</p>
<p>On the right are four controls:</p>
<table class='md'>
<thead>
<tr><th class='c'>Button Legend</th><th>Description</th></tr>
</thead>
<tbody>
<tr><td class='c uni'>S+ (or S-)</td><td>Shows or hides all source code listings. Disabled if none present in document.<br/>
Helpful if using 'find on page' browser text search.</td></tr>
<tr><td class='c'><strong></td><td></td></tr>
<tr><td class='c'><strong></td><td></td></tr>
<tr><td class='c uni'>LIST</td><td>Toggles LIST pane visibility.</td></tr>
<tr><td class='c uni'>TOC</td><td>Toggles TOC pane visibility.</td></tr>
<tr><td class='c' ><svg class="svg_settings" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19.43 12.98c.04-.32.07-.64.07-.98s-.03-.66-.07-.98l2.11-1.65c.19-.15.24-.42.12-.64l-2-3.46c-.12-.22-.39-.3-.61-.22l-2.49 1c-.52-.4-1.08-.73-1.69-.98l-.38-2.65C14.46 2.18 14.25 2 14 2h-4c-.25 0-.46.18-.49.42l-.38 2.65c-.61.25-1.17.59-1.69.98l-2.49-1c-.23-.09-.49 0-.61.22l-2 3.46c-.13.22-.07.49.12.64l2.11 1.65c-.04.32-.07.65-.07.98s.03.66.07.98l-2.11 1.65c-.19.15-.24.42-.12.64l2 3.46c.12.22.39.3.61.22l2.49-1c.52.4 1.08.73 1.69.98l.38 2.65c.03.24.24.42.49.42h4c.25 0 .46-.18.49-.42l.38-2.65c.61-.25 1.17-.59 1.69-.98l2.49 1c.23.09.49 0 .61-.22l2-3.46c.12-.22.07-.49-.12-.64l-2.11-1.65zM12 15.5c-1.93 0-3.5-1.57-3.5-3.5s1.57-3.5 3.5-3.5 3.5 1.57 3.5 3.5-1.57 3.5-3.5 3.5z"></path></svg>
</td><td>Shows Settings window.</td></tr>
</tbody>
</table>
<p>If both the LIST and TOC are either docked or floating, and one's window width is
either narrow or medium, the LIST and TOC buttons can be used to toggle the LIST/TOC pane
display (ie, they are mutually exclusive). </p>
<h2>LIST Pane Controls</h2>
<p><img src="assets/yard-t2_list.png" alt="List Header"></p>
<p>The LIST pane shows collections of items in the library. Typically, this would
be three collections:</p>
<ul>
<li><strong>Classes</strong> - All modules / classes in the library. Items are shown nested
by namespace.</li>
<li><strong>Methods</strong> - All methods contained in the library. It may also include
constants and/or global variables.</li>
<li><strong>Exceptions</strong> (optional) - if shown, all exception classes are removed
from the 'Classes' list and shown in a tree view.</li>
<li><p><strong>Constants</strong> (optional)</p></li>
<li><p><strong>Docs</strong> - Any additional documents included in the library.</p></li>
</ul>
<p>Other collections may also be shown.</p>
<p>Other than the list / collection menu, there are:</p>
<ul>
<li>a search text box - allows searching in the current list</li>
<li>a resizer control - controls the width of the pane</li>
<li>global tree open/close controls - if the current list is a treeview, the plus
and minus controls will open / close all nodes</li>
</ul>
<h3>List Search</h3>
<p>Search allows searching both the name of the object and the namespace. The
delimiter is the <strong>last</strong> namespace delimiter (<code>::</code> in Ruby).</p>
<p>The search string is divided at that mark; everything to the left is used to
search the namespace, everything to the right is used to search the name.</p>
<p>If there is no namespace delimiter, the string is used for name search.</p>
<h4>Name Search</h4>
<p>Searching allows both 'in string' and 'start of string' searching of the object
name. 'Start of string' searching is done by capitalizing the first character of
the search name string.</p>
<p>Name search is case insensitive.</p>
<p>When searching the methods list, one can use a period (<code>.</code>) to
restrict the search to class methods, and a hash (<code>#</code>) for instance methods.</p>
<h4>Namespace Search</h4>
<p>Namespace search is case sensitive. It will also search for more than one term.
In regex terms, a string like <code>Record::ClassMethods::</code> will use a regex of
<code>/Record([^:]*::[^:]*)+?ClassMethods/</code> to search the namespace string.</p>
<h4>Name Only Search Examples</h4>
<p><code>Class</code> - 'Methods' list - will find all methods starting with <code>class</code></p>
<p><code>.Ab</code> - 'Methods' list - will find all class methods starting with <code>ab</code></p>
<p><code>#class</code> - 'Methods' list - will find all instance methods whose name contains
<code>class</code></p>
<h4>Namespace Only Search Examples</h4>
<p><code>Record::Class::</code> - 'Methods' list - will show all methods shown in namespaces
containing <code>Record</code> followed by <code>Class</code></p>
<h4>Combined Search Examples</h4>
<p><code>Active::Class::attr</code> - 'Methods' list - will show all methods shown in namespaces
containing <code>Active</code> followed by <code>Class</code> and whose name contains with <code>attr</code></p>
<p><code>Active::ClassMethods</code> - 'Classes' list - will show all classes in a namespace
containing <code>Active</code>, named <code>ClassMethods</code></p>
<h2>TOC Pane Controls</h2>
<table class='md'><tbody>
<tr><td width='280px'><img width='271' src='assets/yard-t2_toc.png' /></td>
<td><p>The TOC pane has the same controls as the LIST pane, and allows searching for
methods in the current document.</p>
<p>When searching for method names, if there are multiple methods with the same name,
the results will show them in call order, top called first, then down the list.</p>
<p>This is shown at left for
<a href='https://msp-greg.github.io/rails_master/ActiveRecord/Base.html'>Rails ActiveRecord::Base</a>,
which is a class with no 'traditional' natively defined methods.</p>
<p>At present, method search does not allow namespace search.</p>
</td></tr>
</tbody>
</table>
<h2>Settings Window</h2>
<table class='md'><tbody>
<tr><td width='280px'><img width='262' src='assets/yard-t2_settings.png' /></td>
<td><p>The settings windows allows one to change the font size and locations of
the LIST and TOC panes. The pane location settings are for the current window
and font size. The location (docked/floating) settings are stored separately for
medium and wide window widths.</p>
<p>'Mono Chars' is the number of monospaced characters that fit the window and
screen at the current font size. 'Docked Panes' is the number of allowed docked
panes. The breaks between narrow/medium/wide are 110 and 160 monospaced characters.
</td></tr>
</tbody>
</table>
<h2>MAIN Pane Layout and Controls</h2>
<p>The main pane shows the current object / document.</p>
<p>Code documents contain the following sections:</p>
<h3>Relationships & Source Files</h3>
<ul>
<li><strong>Namespace Children</strong>
<ul>
<li>Modules:</li>
<li>Classes:</li>
<li>Exceptions:</li>
</ul></li>
<li><strong>Extension / Inclusion / Inheritance Descendants</strong>
<ul>
<li>Extended In:</li>
<li>Included In:</li>
<li>Prepended In:</li>
<li>Subclasses:</li>
</ul></li>
<li><strong>Super Chains via Extension / Inclusion / Inheritance</strong>
<ul>
<li>Class Chain: - roughly equivalent to <code>.singleton_class.ancestors</code></li>
<li>Instance Chain: - roughly equivalent to <code>.ancestors</code></li>
</ul></li>
<li><strong>Inherits:</strong> - shows inheritance tree for classes</li>
<li><strong>Defined In:</strong> - lists all files that the object is defined in</li>
</ul>
<h3>Overview</h3>
<p>Shows comment documentation for the class/module.</p>
<h3>Summary Sections</h3>
<p>These sections show a summary description of the items (both native and chained)
available to the class/module.</p>
<p>The default sections are listed below, but additional sections maybe added by comments.
In Rails libraries, <code>included do</code> calls may add native items to a class / module. These
items are listed by the module that contains the <code>included do</code> call.</p>
<ul>
<li>Constant Summary</li>
<li>Class Attribute Summary</li>
<li>Class Method Summary</li>
<li>Instance Attribute Summary</li>
<li>Instance Method Summary</li>
</ul>
<p>In each default section, native items are shown first, then the 'super' items, in
call order, grouped by owner object. Note that the descriptions are essentially
summaries, or the first sentence of the description. Full descriptions and source
code are available in the 'Detail' sections. The items names link to the 'Details'
section listing, and for 'super' items, lead to another document.</p>
<p>Methods are sorted by:</p>
<ol>
<li>nodoc status (if nodoc objects are shown)</li>
<li>visibility (public, protected, private)</li>
<li>whether they are module functions or read / write attributes</li>
<li>alphabetically</li>
</ol>
<h3>Detail Sections</h3>
<p>Only native items are show in Detail sections. Full description and source code
are shown. Items are sorted alphabetically.</p>
<ul>
<li>Constructors</li>
<li>Class Attribute Detail</li>
<li>Class Method Detail</li>
<li>Instance Attribute Detail</li>
<li>Instance Method Detail</li>
</ul>
<h3>Additional Code Document Notes</h3>
<p>The 'Relationships & Source Files', 'Overview', and 'Summary' sections can be
collapsed, and the three settings hold for both the session and the site.</p>
<h2>Key Assignments</h2>
<h3>Standard Keys</h3>
<ul>
<li>If the LIST pane is visible and it is showing the method list, hitting any key
will move the list to the top 'first character' match.</li>
<li>Hitting escape will empty the LIST pane search input box, resetting the LIST
pane to the current list. Note that this will not reload the list from the server.</li>
</ul>
<h3>Alt-Control Keys</h3>
<table class='md'>
<thead><tr>
<th class='c'>Key</th>
<th style="text-align: left">Result</th>
</tr></thead>
<tbody><tr>
<td class='c'><strong>c</strong></td>
<td>Shows and loads the 'Class List', will show the LIST pane if it's not visible</td>
</tr><tr>
<td class='c'><strong>d</strong></td>
<td>Shows and loads the 'Docs List', will show the LIST pane if it's not visible</td>
</tr><tr>
<td class='c'><strong>m</strong></td>
<td>Shows and loads the 'Method List', will show the LIST pane if it's not visible</td>
</tr><tr>
<td class='c'><strong></td>
<td></td>
</tr><tr>
<td class='c'><strong>i</strong></td>
<td>If 'index' is shown in the header path, it will go to the index page</td>
</tr><tr>
<td class='c'><strong>l</strong></td>
<td>Shows / Hides the LIST pane, does not reload</td>
</tr><tr>
<td class='c'><strong>s</strong></td>
<td>Set focus to the LIST pane search input box, will show the LIST pane if it's not visible</td>
</tr><tr>
<td class='c'><strong>t</strong></td>
<td>Shows / Hides the TOC pane</td>
</tr></tbody>
</table>
<h2>Methods</h2>
<ul>
<li><p>RDoc lists class methods as <code>::name</code>, YARD uses <code>.name</code>. YardT2 uses <code>.name</code>.</p></li>
<li><p>In the Method List, TOC and collapsed summary sections, methods are coded with
symbols that show their properties, as shown below:</p></li>
</ul>
<table class='md'>
<thead><tr>
<th class='c'>Symbol</th>
<th style='text-align: left'>Desc</th>
<th class='gap'></th>
<th class='c'>Symbol</th>
<th style='text-align: left; width: 12rem;'>Desc</th>
</tr></thead>
<tbody><tr>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M0 5.5 L4.5 2 9 5.5 4.5 9' fill='hsl(30,100%,50%)'/></svg></td>
<td>Protected</td>
<td class='gap'></td>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M0 5.5 L4.5 1.5 9 5.5 4.5 9.5' fill='hsl(170,95%,37%)'/></svg></td>
<td>Attribute - Read / Write</td>
</tr><tr>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M4.5 1 L8 5.5 4.5 10 1 5.5' fill='hsl(358,100%,48%)'/></svg></td>
<td>Private</td>
<td class='gap'></td>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M0 1.5 L9 5.5 0 9.5' fill='hsl(100,100%,35%)'/></svg></td>
<td>Attribute - Read Only</td>
</tr><tr>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M4 1 6 1 6 9 4 9' fill='hsl(0,100%,45%)'/></td>
<td>nodoc</td>
<td class='gap'></td>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M0 5.5 L9 1.5 9 9.5' fill='hsl(210,90%,40%)'/></svg></td>
<td>Attribute - Write Only</td>
</tr><tr>
<td></td><td></td>
<td class='gap'></td>
<td class='c'><svg viewBox='0 0 11 10' xmlns='http://www.w3.org/2000/svg'><path d='M1 3 L9 3 9 8 1 8' fill='hsl(30,80%,32%)'/></svg></td>
<td>Module Function</td>
</tr></tbody>
</table>
<h3>Constructors</h3>
<p>YARD lists standard constructors (<code>def initialize</code>) as an <code>#initialize</code> instance method,
RDoc lists them as a <code>.new</code> class method. YardT2 uses the <code>.new</code> class form.
Since some code uses both <code>.new</code> and <code>#initialize</code>, YardT2 attempts to list both
in the 'Constructor Details' section.</p>
<p>Note that in modules which have 'constructors' for inclusion, the method is left
as an instance method (<code>#initialize</code>). </p>
<h3>Attributes</h3>
<p>Any object created via Ruby or c attribute statements is listed as an attribute.
Methods are also listed as attributes based on their signature.</p>
<p>For instance, if a method has one required parameter and its name ends with an
equal sign (=), it will be considered a write attribute.</p>
<p>Conversely, if both read and write method pairs are created (ie, meth and meth=),
they will be listed as attributes only if both are valid attributes – the read
method must have no parameters, and the write method must have only one required
parameter. If not, they will be listed (together) in the 'Methods' sections.</p>
<p>Any attributes created via attr_accessor (and without any additional code) are
only listed via the read name, but will show a read /write symbol in the Method List.</p>
<h3>Aliases</h3>
<p>All aliases are listed in the summary and detail sections, and also in the method
list. Documentation is only listed for the 'main' method, the others link to it.
Since Ruby c libraries often create aliases without using an alias 'directive',
the code guesses as to which method should be considered the 'main' method.</p>
<style type='text/css' media='screen'>
table.md th, table.md td { border: 0 none #fff; padding: 0.133334em 0.466667em; text-align: left; }
table.md thead tr { border-bottom: 1px solid #888; }
table.md td, table.md th { vertical-align: top; }
table.md tr:nth-child(even) { background: #fff; }
table.md tr:nth-child(odd) { background: #fff; }
table.md th.c, table.md td.c { text-align: center; }
table.md td.uni { font-family: 'Lucida Sans', Arial, sans-serif; }
table.md td.gap { width: 2em; }
table.md th.gap { width: 2em; border-bottom: 1px solid transparent; }
table.md svg { width: 22px; height: 20px; }
img { margin-top: 0.4em; max-width: 100%; }
</style>
<div id='footer'>
Generated by
<a href='http://yardoc.org' title='Yay! A Ruby Documentation Tool' target="_parent">yard</a>
0.9.36 with <a href='https://msp-greg.github.io/yard-t2/' title='yard-t2' target="_parent">yard-t2</a> 0.9.0 (ruby 3.4.0dev 2024-11-22)
</div>
</div> <!-- content -->
</div> <!-- y_main -->
</body>
</html>