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 new file mode 100644 index 0000000000..798dde517c --- /dev/null +++ b/doc/rdoc/rdoc_sources.md @@ -0,0 +1,77 @@ +# \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, reads files and directories starting in `'.'` +the current working directory. + +When anq 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 + +Based on the file extension of a file name, +\RDoc assumes its content to be one of these: + +- `.rb`, `.rbw`: 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. +- _Anything else_: Text file in `rdoc` (markup) format. + +In Ruby or C code, some documentation is derived from the code itself. + +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`; + see RDoc::Markdown. +- `rd`; + see [RD Working Draft][rd working draft]. +- `tomdoc`; + see [Tomdoc for Ruby][tomdoc for ruby]. + +## Document-Control Files + +A directory may have a document-control file, named `.document`. + +- 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-control file is simple: + +- Each line may contain a _pattern_, which may be: + + - 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). + +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 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 +[rd working draft]: https://github.com/uwabami/rdtool/blob/master/doc/rd-draft.rd +[tomdoc for ruby]: http://tomdoc.org