From 429f9ecebb880e4e70cb616429017e8e376c5f31 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 1 Sep 2025 11:47:17 -0500 Subject: [PATCH 1/3] [DOC] RDoc Sources --- doc/rdoc/rdoc_sources.md | 70 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 doc/rdoc/rdoc_sources.md diff --git a/doc/rdoc/rdoc_sources.md b/doc/rdoc/rdoc_sources.md new file mode 100644 index 0000000000..92833670ee --- /dev/null +++ b/doc/rdoc/rdoc_sources.md @@ -0,0 +1,70 @@ +# \RDoc Sources + +\RDoc derives Ruby documentation from files +that are selected by \RDoc defaults and by user specifications. + +\RDoc reads files and directories specified as arguments +on the `rdoc` command line; +if no arguments are given, \RDoc reads `'.'` (the current working directory): + +- For each given file path \RDoc reads the file. +- For each given directory path, + \RDoc (by default) recursively reads all directories and files in the directory tree. + You can restrict the and directories and files to be read by creating + [.document files][document files]. + +## File Types + +Based on the file extension of a file name, +\RDoc assumes its content to be one of these: + +- `.rb`: Ruby code. +- `.c`, `.h`, `.C`, `.H`: C code. +- `.rdoc`: Text file in `rdoc` (markup) format. +- `.md`: Text file in `markdown` format. +- `.rd`: Text file in `rd` format. + +In Ruby or C code, documentation is derived from the code itself, +and may also be derived from the text of comments; +that text may be in any of these formats +(see [directive :markup:][directive markup]). + +- `rdoc` (markup); + see RDoc::MarkupReference. +- `markdown`; + see RDoc::Markdown. +- `rd`; + see [RD Working Draft][rd working draft]. +- `tomdoc`; + see [Tomdoc for Ruby][tomdoc for ruby]. + +## `.document` Files + +When \RDoc reads a directory, +it first looks for a file named `.document`: + +- If the file does not exist, + \RDoc reads all files in the directory, + and reads its subdirectories. +- It the file exists, + \RDoc reads only the files and subdirectories specified there. + +The format of the `.document` file is simple: + +- Each line may contain a _pattern_, which may be: + + - A file path. + - A directory path. + - A file glob, such as `*.rb` or `C*`. + +- A line may contain only one pattern (no whitespace- or comma-separated multiple patterns). +- A pattern may be followed (on the same line) by a comment (beginning with `'#'`). +- An entire line may be a comment (beginning with `'#'`). +- A line may be blank (empty). + +Any directory in the filetree may contain a `.document`file. + +[document files]: rdoc-ref:rdoc_sources.md@.document+Files +[directive markup]: https://ruby.github.io/rdoc/RDoc/MarkupReference.html#class-RDoc::MarkupReference-label-3Amarkup-3A +[rd working draft]: https://github.com/uwabami/rdtool/blob/master/doc/rd-draft.rd +[tomdoc for ruby]: http://tomdoc.org From f1d653ecb5af86e87c5d1f37c4057937fd4ca32a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 1 Sep 2025 14:12:16 -0500 Subject: [PATCH 2/3] [DOC] RDoc Sources --- doc/rdoc/rdoc_sources.md | 54 ++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/doc/rdoc/rdoc_sources.md b/doc/rdoc/rdoc_sources.md index 92833670ee..f02592c4e2 100644 --- a/doc/rdoc/rdoc_sources.md +++ b/doc/rdoc/rdoc_sources.md @@ -3,15 +3,16 @@ \RDoc derives Ruby documentation from files that are selected by \RDoc defaults and by user specifications. -\RDoc reads files and directories specified as arguments -on the `rdoc` command line; -if no arguments are given, \RDoc reads `'.'` (the current working directory): +\RDoc reads files and directories specified as arguments on the `rdoc` command line +(`'.'` if no arguments given). -- For each given file path \RDoc reads the file. -- For each given directory path, - \RDoc (by default) recursively reads all directories and files in the directory tree. - You can restrict the and directories and files to be read by creating - [.document files][document files]. +When the argument is: + +- A file path: \RDoc reads the file. +- A directory path: + \RDoc (by default) recursively reads all files and directories in the directory tree. + You can restrict the files and directories to be read; + see [Document-Control Files][document-control files]. ## File Types @@ -23,12 +24,14 @@ Based on the file extension of a file name, - `.rdoc`: Text file in `rdoc` (markup) format. - `.md`: Text file in `markdown` format. - `.rd`: Text file in `rd` format. +- _Anything else_: Text file in `rdoc` (markup) format. + +In Ruby or C code, some documentation is derived from the code itself. -In Ruby or C code, documentation is derived from the code itself, -and may also be derived from the text of comments; +Additional documentation may be derived from the text in comments; that text may be in any of these formats (see [directive :markup:][directive markup]). - + - `rdoc` (markup); see RDoc::MarkupReference. - `markdown`; @@ -38,33 +41,36 @@ that text may be in any of these formats - `tomdoc`; see [Tomdoc for Ruby][tomdoc for ruby]. -## `.document` Files +## Document-Control Files -When \RDoc reads a directory, -it first looks for a file named `.document`: +A directory may have a document-control file, named `.document`. -- If the file does not exist, - \RDoc reads all files in the directory, - and reads its subdirectories. -- It the file exists, +- If a directory _does not_ have document-control file, + \RDoc reads all its files and subdirectories. +- If directory _does have_ a document-control file, \RDoc reads only the files and subdirectories specified there. -The format of the `.document` file is simple: +The format of the document-control file is simple: - Each line may contain a _pattern_, which may be: - - A file path. - - A directory path. - - A file glob, such as `*.rb` or `C*`. + - A file path; e.g., `foo.rb`, `lib/bar.rb`. + - A directory path; e.g., `subdir`, `subdir/subsubdir`. + - A file glob; e.g., `*.rb`, `C*`, `lib/*.rb`. - A line may contain only one pattern (no whitespace- or comma-separated multiple patterns). - A pattern may be followed (on the same line) by a comment (beginning with `'#'`). - An entire line may be a comment (beginning with `'#'`). - A line may be blank (empty). -Any directory in the filetree may contain a `.document`file. +Each directory in the filetree may (or may not) contain a document-control file. + +Note that a document-control file in a subdirectory is read _after_ document-control files +in directories above it; +therefore if file `parent/.document` specifies `child/foo.rb`, +then `child/foo.rb` is to be read regardless of the content of `child/.document`. -[document files]: rdoc-ref:rdoc_sources.md@.document+Files +[document-control files]: rdoc-ref:rdoc_sources.md@Document-Control+Files [directive markup]: https://ruby.github.io/rdoc/RDoc/MarkupReference.html#class-RDoc::MarkupReference-label-3Amarkup-3A [rd working draft]: https://github.com/uwabami/rdtool/blob/master/doc/rd-draft.rd [tomdoc for ruby]: http://tomdoc.org From 7b4f85a39d85d6fa9cd9459c7ac7d1d0e766dc4f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 3 Sep 2025 15:50:32 -0500 Subject: [PATCH 3/3] [DOC] RDoc Sources --- .document | 3 ++- doc/rdoc/rdoc_sources.md | 11 ++++++----- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.document b/.document index fe7bc0def1..d02fec6fbc 100644 --- a/.document +++ b/.document @@ -1,4 +1,5 @@ *.md *.rdoc lib -doc +doc/rdoc/* + diff --git a/doc/rdoc/rdoc_sources.md b/doc/rdoc/rdoc_sources.md index f02592c4e2..798dde517c 100644 --- a/doc/rdoc/rdoc_sources.md +++ b/doc/rdoc/rdoc_sources.md @@ -3,10 +3,11 @@ \RDoc derives Ruby documentation from files that are selected by \RDoc defaults and by user specifications. -\RDoc reads files and directories specified as arguments on the `rdoc` command line -(`'.'` if no arguments given). +\RDoc reads files and directories specified as arguments on the `rdoc` command line; +if no arguments are given, reads files and directories starting in `'.'` +the current working directory. -When the argument is: +When anq argument is: - A file path: \RDoc reads the file. - A directory path: @@ -19,7 +20,7 @@ When the argument is: Based on the file extension of a file name, \RDoc assumes its content to be one of these: -- `.rb`: Ruby code. +- `.rb`, `.rbw`: Ruby code. - `.c`, `.h`, `.C`, `.H`: C code. - `.rdoc`: Text file in `rdoc` (markup) format. - `.md`: Text file in `markdown` format. @@ -68,7 +69,7 @@ Each directory in the filetree may (or may not) contain a document-control file. Note that a document-control file in a subdirectory is read _after_ document-control files in directories above it; therefore if file `parent/.document` specifies `child/foo.rb`, -then `child/foo.rb` is to be read regardless of the content of `child/.document`. +then `child/foo.rb` is read regardless of the content of `child/.document`. [document-control files]: rdoc-ref:rdoc_sources.md@Document-Control+Files [directive markup]: https://ruby.github.io/rdoc/RDoc/MarkupReference.html#class-RDoc::MarkupReference-label-3Amarkup-3A