rdoc icon indicating copy to clipboard operation
rdoc copied to clipboard

If any file changed only parse all files if `force-update` is true

Open p8 opened this issue 1 year ago • 3 comments

Commit 13e9a44896323535329331ffbc6c11813da53161 enforced parsing all files if any file is newer than the previous parse, not only updated files.

However, this did not take into account the --force-update option and would parse all files even if --force-update was false.

After this commit, if --force-update is false, only files newer than the previous parse will be parsed. If --force-update is true (the default), all files will be parsed if any file newer than the previous parse.

p8 avatar Jan 30 '24 20:01 p8

This breaks references to labels in unchanged files from a newer file.

nobu avatar Jan 31 '24 01:01 nobu

Maybe I'm missing some context here, but I think currently RDoc works as follows:

  1. Parse all files and generate RDoc files for all files if any file is newer than the last parse.
  2. Don't parse/generate any files if --no-force-update option is passed and no file is newer than the last parse.

This seems to make the --no-force-update option obsolete because it will only not generate any files if no files changed.

There doesn't seem to be an option to only update a single RDoc generated file. It either generates all files or no files. So testing a small change in the documentation in a single file will always generate all RDoc files. For large projects with a lot of files, this could take some time.

With this change, to not break references to labels the --no-force-update option should be skipped. As --force-update is true by default, it will generate all files when a single file is updated.

Commit 13e9a44896323535329331ffbc6c11813da53161 also specifically mentions --force-update:

This commit makes --force-update option enforce to parse all files if any file is newer than the previous parse, not only updated files.

But that commit enforces parsing all files with the --no-force-update option as well.

p8 avatar Jan 31 '24 11:01 p8

RDoc can detect labels only in parsed files, and to tell if words look like labels are really labels, it needs to parse those files actually.

Consider a project that has two files, foo.rb and bar.rb.

# foo.rb

# Uses Bar
class Foo 
end
# bar.rb

# Used by Foo
class Bar
end

rdoc . parses both files, and report as Files: 2 and Classes: 2.

Now you touch one, foo.rb, and run rdoc --no-force-update, with your patched version. Then reported as Files: 1 and Classes: 1, as you expected. But now the updated file doc/Foo.html does not contain a link to Bar.html. Again touch the other bar.rb and re-generate, in this time doc/Bar.html looses the link too.

nobu avatar Feb 18 '24 16:02 nobu