Fix orphaned-block tag bleed and silent NAMESPACE directive drops#19
Merged
Conversation
…ectives Two fixes for document() rewriting NAMESPACE more aggressively than the tags imply: - parse_file() grouped #' runs separated by blank lines or plain comments into one block, so an orphaned block's @export (its function moved or deleted) bled into the next function's block and exported it, @nord and dot-prefix notwithstanding (#18). Blocks are now strictly consecutive #' lines, roxygen2-style. Blank lines and plain # comments between a block and its object are still allowed; a block followed by another block or EOF warns instead of being silently dropped. - write_namespace() silently discarded hand-added NAMESPACE directives (e.g. a manual useDynLib line with no backing @useDynLib tag) on every overwrite (#17). It now warns with the dropped lines and points at the matching tag. export() and S3method() churn is exempt. Also demote cran.R's file header from #' to # (it now attaches to WEBSERVICE_PACKAGES under the new rules) and document the pkg_generics parameter of detect_s3_method() and generate_rd(), which warned on every document() run.
This was referenced Jun 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #17, fixes #18.
Both issues turned out to be the same class: document() rewriting NAMESPACE more aggressively than the tags imply, silently.
#18 root cause was not @nord handling (a clean @nord block was already correct). parse_file() merged
#'runs separated by blank lines or plain comments into one block. So an orphaned block whose function had been moved or deleted bled its @export into the next block:parsed as one block with both @export and @nord, giving
export(.split_text_chunks)and no Rd. This is exactly what happened in chatterbox's tts.R. Blocks are now strictly consecutive#'lines (roxygen2 semantics), and an orphaned block warns instead of being silently dropped. Plain#comments between a block and its function still attach (also roxygen2 semantics; previously the block was silently lost).#17: the @useDynLib tag has worked since January (
#' @useDynLib pkg, .registration = TRUEabove aNULL), but a hand-maintained useDynLib line in NAMESPACE was wiped on every document() run with no signal, and an orphaned tag attempt (e.g. at end of file) failed silently too. Now: write_namespace() warns with the exact dropped lines and the tag to use, and the orphan warning from the #18 fix covers the failed-placement case. export()/S3method() churn is exempt from the warning.Also in this PR: cran.R's
#'file header demoted to plain comments (under the new attachment rules it would document WEBSERVICE_PACKAGES), and four internal functions gained the missing@param pkg_genericsthat warned on every document() run.Tests: 173 pass, including new regression tests for the merge bleed, comment-tolerant attachment, orphan warnings, and the directive-drop warning.