Skip to content

Support ESS-style comment symbol ##' as well#27

Merged
TroyHernandez merged 2 commits into
cornball-ai:mainfrom
eddelbuettel:feature/ess_comments
Jun 24, 2026
Merged

Support ESS-style comment symbol ##' as well#27
TroyHernandez merged 2 commits into
cornball-ai:mainfrom
eddelbuettel:feature/ess_comments

Conversation

@eddelbuettel

@eddelbuettel eddelbuettel commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

When one uses Emacs and ESS, it becomes second nature to use ##' as the dual # is different from #: the latter gets (by convention) indented to middle of the screen (for comments following a statement, typically) whereas ##' stays flush.

In fact, when one writes a simple function, say

emptydemo <- function(foo = 42L) {
    foo
}

and then asks for the documentation template (via C-c C-o C-c, or via the menu, or via the function) then one gets

##' .. content for \description{} (no empty lines) ..
##'
##' .. content for \details{} ..
##' @title 
##' @param foo 
##' @return 
##' @author Dirk Eddelbuettel
emptydemo <- function(foo = 42L) {
    foo
}

(where one can question the wisdom of doing @title by tag and @detail and @description by placement, but that is how they role; addiing @author is) which is clearly using ##'. That used to stop tinyrox in its tracks.

Following the PR if I invoke trox.r (as I live on the command-line for these things) we get

% tinyrox says don't edit this manually, but it can't stop you!
\name{emptydemo}
\alias{emptydemo}
\title{}
\usage{
emptydemo(foo = 42L)
}
\arguments{
\item{foo}{}
}
\value{

}
\description{
.. content for \details{} ..
}

and life is good. I looked for the exising ^#' regular expressions (and variants) and made them ^##?' which should allow for everything that was done before (when ? acts as 'add zero instances of the preceding symbol' as well as the desired new feature demonstrated here (when ? adds exactly one).

eddelbuettel and others added 2 commits June 24, 2026 07:31
PR cornball-ai#27 relaxed the doc-line regexes to ^##?' but left the two ^\\s*#' checks in the orphaned-block detector (parse.R:55,60) unchanged, so a stray ##' block bled into the next object instead of warning (the cornball-ai#18 regression, for double-hash comments). Extend those two checks and add test_parse.R coverage for ##' parsing and ##' orphan detection.
@TroyHernandez TroyHernandez merged commit bc35cb6 into cornball-ai:main Jun 24, 2026
2 checks passed
@eddelbuettel

Copy link
Copy Markdown
Collaborator Author

Thanks for the follow-up, and merge!

@eddelbuettel eddelbuettel deleted the feature/ess_comments branch June 24, 2026 13:43
@eddelbuettel eddelbuettel restored the feature/ess_comments branch June 24, 2026 13:43
@eddelbuettel eddelbuettel deleted the feature/ess_comments branch June 24, 2026 13:44
@TroyHernandez

Copy link
Copy Markdown
Contributor

Thanks for the PR!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants