More docs

NEWS.md

@@ -35,7 +35,7 @@
 - Documentation overhaul: New README, new "Get started" pkgdown page, new
   vignettes on `strict = FALSE`, `Adoption` renamed to `Third-party
   integrations`, minor other doc improvements (#741, #643, #618, #614, #677,
-  #651, #667, #672, #687, #752).
+  #651, #667, #672, #687, #752, #754).
 
 - `@exampleIsf` roxygen tag for conditional examples is now supported (#743).
 

R/rules-spaces.R

@@ -232,12 +232,18 @@ set_space_between_levels <- function(pd_flat) {
 #' Start comments with a space
 #'
 #' Forces comments to start with a space, that is, after the regular expression
-#' "^#+'*", at least one space must follow if the comment is *non-empty*, i.e
+#' `#+['\\*]`, at least one space must follow if the comment is *non-empty*, i.e
 #' there is not just spaces within the comment. Multiple spaces may be legit for
 #' indention in some situations.
+#' @section Exceptions:
+#' Spaces won't be added to comments when they are:
+#'
+#' * shebangs
+#' * code chunk headers
+#' * xaringan markers
+#'
 #' @param pd A parse table.
-#' @param force_one Whether or not to force one space or allow multiple spaces
-#'   after the regex "^#+'*".
+#' @param force_one Whether or not to force one space or allow multiple spaces.
 #' @importFrom purrr map_chr
 #' @keywords internal
 start_comments_with_space <- function(pd, force_one = FALSE) {