-
Notifications
You must be signed in to change notification settings - Fork 235
/
NEWS.md
1447 lines (990 loc) · 55.6 KB
/
NEWS.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# roxygen2 (development version)
* `@family` lists are now ordered more carefully, "foo1" comes after "foo" (#1563, @krlmlr).
# roxygen2 7.3.0
## New features
* `@docType package` now works more like documenting `"_PACKAGE"`,
creating a `{packagename}-package` alias and clearly suggesting that
you should switch to `"_PACKAGE"` instead (#1491).
* `_PACKAGE` will no longer generate an alias for your package name if
a function of the same name exists (#1160).
* The NAMESPACE roclet now reports if you have S3 methods that are missing
an `@export` tag. All S3 methods need to be `@export`ed (which confusingly
really registers the method) even if the generic is not. This avoids rare,
but hard to debug, problems (#1175). You can suppress the warning with
`@exportS3Method NULL` (#1550).
* The `NAMESPACE` roclet once again regenerates imports _before_ loading
package code and parsing roxygen blocks. This has been the goal for a long
time (#372), but we accidentally broke it when adding support for code
execution in markdown blocks. This resolves a family of problems where you
somehow bork your `NAMESPACE` and can't easily get out of it because you
can't re-document the package because your code doesn't reload.
## Minor improvements and bug fixes
* If you document a function from another package it is automatically
imported. Additionally, if you set `@rdname` or `@name` you can opt out
of the default `reexports` topic generation and provide your own docs
(#1408).
* Generate correct usage for S4 methods with non-syntactic class names.
* The `ROXYGEN_PKG` env var provides the name of the package being documented
(#1517).
* `@describeIn foo` now suggests that you might want `@rdname` instead
(#1493). It also gives a more informative warning if you use it with an
unsupported type (#1490).
* In `DESCRIPTION`, URLs containing escapes in `URL` and `BugReports` are
now correctly handled (@HenningLorenzen-ext-bayer, #1415). Authors can now
have multiple email addresses (@jmbarbone, #1487).
* `escape_examples()` is now exported (#1450).
* `@exportS3Method` provides the needed metadata to generate correct usage
for S3 methods, just like `@method` (#1202).
* `is_s3_generic()` now ignores non-function objects when looking for a
candidate function. I believe this is closer to how R operates.
* `@import` and friends are now ignored if they try to import from the
package being documented. This is useful to add self-dependencies in
standalone files meant to be used in other packages (r-lib/usethis#1853).
* `@importFrom` throws a friendlier error if you try and import a non-existing
functions (@MichaelChirico, #1409).
* `@include` now gives an informative warning if you use a path that doesn't
exist (#1497).
* `@inherit` can now also inherit from `@format` (#1293).
# roxygen2 7.2.3
* roxygen2 now supports HTML blocks in markdown. They are only included
in the HTML manual. They can also be produced as the output of code
chunks.
* Improved support for RStudio IDE.
# roxygen2 7.2.2
* `@includeRmd` calls `local_reproducible_output()` to make code run in
included `.Rmd`s more consistent with other sources (#1431).
* Fix duplicated argument in `roxy_block()` to avoid CRAN removal.
# roxygen2 7.2.1
## Tags
* All built-in tags are now documented so that you can do (e.g.) `?"@param"`
to get a basic description of `@param` and a pointer where to learn more
(#1165). This is powered by a new `tags_list()` lists all tags defined by
roxygen2 and `tags_metadata()` provides some useful information about them
for use by (e.g.) IDEs (#1375).
* `@describeIn` can now be used to combine more types of functions
(generics, methods and other functions) into a single topic.
The resulting section organises the functions by type (#1181)
and displays methods like function calls. Methods are recognized only if
they extend the generic in the destination,or if the destination can
heuristically be identified as a constructor.
* Code evaluated in inline markdown code chunks and `@eval`/`@evalRd`/
`@evalNamespace` is now evaluated in an environment designed to be more
reproducible and to suppress output that won't work in Rd (e.g. turning
off colour and unicode support in cli) (#1351). They now also set
knitr options `comment = #>` (#1380) and `collapse = TRUE` (#1376).
* `@export` will now export both the class and constructor function when
applied to expressions like `foo <- setClass("foo")` (#1216).
* `@includeRmd` now gives better feedback when it fails (#1089).
## (R)markdown
* New `knitr_chunk_options` option (in the `Roxygen` entry of
`DESCRIPTION` or in `man/roxygen/meta.R`) is added to the knitr chunk
options that roxygen2 uses for markdown code blocks and inline
code (#1390).
* PDF figures are only included the PDF manual, and SVG figures are only
included in the HTML manual (#1399).
* You can now use alternative knitr engines in markdown code blocks (#1149).
* Generated HTML for code blocks never includes "NA" for language (#1251).
* Using a level 1 heading in the wrong tag now gives a more useful warning
(#1374).
* Fix bug interpolating the results of indented inline RMarkdown (#1353).
## Other
* If you have a daily build of RStudio, the lists of changed Rd files are
now clickable so you can immediately see the rendered development
documentation (#1354).
* R6 documentation no longer shows inherited methods if there aren't any
(#1371), and only links to superclass docs if they're actually available
(#1236).
* Automated usage no longer mangles nbsp in default arguments (#1342).
# roxygen2 7.2.0
## New features
* The NAMESPACE roclet now preserves all existing non-import directives during
it's first pre-processing pass. This eliminates the "NAMESPACE has changed"
messages and reduces the incidence of namespace borking (#1254).
* `@inheritParams` now only inherits exact multiparameter matches, so if you're
inheriting from a function with `@param x,y` you'll only get the parameter
documentation if your function needs docs for both x and y (#950).
* All warning messages have been reviewed to be more informative and
actionable (#1317). `@title` now checks for multiple paragraphs.
`@export` gives a more informative warning if it contains too many lines.
(#1074). All tags warn now if only provide whitespace (#1228), and
problems with the first tag in each block are reported with the correct line
number (#1235).
* If you have a daily build of RStudio, roxygen2 warnings will now include a
clickable hyperlink that will take you directly to the problem (#1323).
This technology is under active development across the IDE and the cli
package but is extremely exciting.
## Minor improvements and bug fixes
* roxygen2 can once again read UTF-8 paths on windows (#1277).
* `@author`s are de-duplicated in merged documentation (@DanChaltiel, #1333).
* `@exportS3method pkg::generic` now works when `pkg::generic` isn't
imported by your package (#1085).
* `@includeRmd` is now adapted to change in rmarkdown 2.12 regarding math
support in `github_document()` (#1304).
* `@inherit` and friends perform less aggressive link tweaking, eliminating
many spurious warnings. Additionally, when you do get a warning, you'll
now always learn which topic it's coming from (#1135). Inherited
`\ifelse{}{}{}` tags are now inserted correctly (without additional `{}`)
(#1062).
* `@inherit` now supports inheriting "Notes" with `@inherit pkg::fun note`
(@pat-s, #1218)
* Automatic `@usage` now correctly wraps arguments containing syntactically
significant whitespace (e.g anonymous functions) (#1281) and non-syntactic
values surrounded by backticks (#1257).
* Markdown:
* Code blocks are always wrapped in `<div class="sourceCode">`
even if the language is unknown (#1234).
* Links with markup (e.g. ``[foo `bar`][target]``) now cause an informative
warning instead of generating invalid Rd.
* Curly braces in links are now escaped (#1259).
* Inline R code is now powered by knitr. Where available, (knit) print
methods are applied (#1179). This change alters outputs and brings roxygen
in line with console and R markdown behavior. `x <- "foo"` no longer
inserts anything into the resulting documentation, but `x <- "foo"; x`
will. This also means that returning a character vector will insert
commas between components, not newlines.
* roxygen2 no longer generates invalid HTML (#1290).
* DOIs, arXiv links, and urls in the `Description` field of the `DESCRIPTION`
are now converted to the appropriate Rd markup (@dieghernan, #1265, #1164).
DOIs in the `URL` field of the `DESCRIPTION` are now converted to Rd's
special `\doi{}` tag (@ThierryO, #1296).
# roxygen2 7.1.2
* The new `@examplesIf` tag can be used to create conditional
examples. These examples only run if a specified condition
holds (#962).
* roxygen2 is now licensed as MIT (#1163).
* Bug fix for upcoming stringr 2.0.0 release.
* Code blocks with language now add `sourceCode` to the generated div; this
makes syntax highlighting more consistent across downlit/pandoc/knitr/roxygen2.
* Percent signs in markdown link targets, e.g. `[text](https://foo/ba%20r)`
are now handled correctly (#1209).
# roxygen2 7.1.1
* When processing cross package markdown links (e.g. `[pkg::fun()]`),
roxygen2 now looks up the file it needs to link to, instead of linking to
the topic, to avoid "Non-file package-anchored links" `R CMD check` warnings.
* R6 methods and re-exported functions are always sorted in the C locale;
this ensures they're always sorted the same way in every environment (#1077).
* roxygen2 now supports inline markdown code and code chunks inside
Rd tags. In particular in `\out{}` (#1115).
# roxygen2 7.1.0
## New features
* roxygen2 now supports inline markdown code and also code chunks,
using the same notation as the knitr package. For example:
```R
#' This manual was generated at: `r Sys.time()`.
#' ...
#' `mtcars` is a data frame with `r ncol(mtcars)` columns, here
#' is a summary of them:
#'
#' ```{r}
#' summary(mtcars)
#' ```
```
See `vignette("rd-formatting")` for details.
* roxygen2 now keeps using Windows (CR LF) line endings for files that
already have CR LF line endings, and uses LF for new files (#989).
## Minor improvements and bug fixes
* Auto-generated package documentation can now handle author ORCID comments
containing full url (#1040).
* Hyperlinks to R6 methods are also added in the PDF manual (#1006).
* Empty annotations (alternate text) for figures added via markdown are now
omitted. This caused issues when generating pkgdown web sites (#1051).
* Roxygen metadata can now have a `packages` element, giving a character vector
of package names to load. This makes it easier to use extension package that
provide new tags for existing roclets (#1013). See `?load_options` for
more details.
```yaml
Roxygen: list(markdown = TRUE, packages = "roxygenlabs")
```
* `@evalNamespace()` works again (#1022).
* `@description NULL` and `@details NULL` no longer fail; instead, these tags
are ignored, except for `@description NULL` in package level documentation,
where it can be used to suppress the auto-generated Description section
(#1008).
* Multiple `@format` tags are now combined (#1015).
* The warning for `@section` titles spanning multiple lines now includes a
hint that you're missing a colon (@maelle, #994).
* Can now document objects created with `delayedAssign()` by forcing
evaluation at documentation time (#1041)
# roxygen2 7.0.2
* `\example{}` escaping has been improved (again!) so that special escapes
within strings are correctly escaped (#990).
# roxygen2 7.0.1
* `@includeRmd` has now an optional second argument, the top level section
the included file will go to. It defaults to the details section (#970).
Code chunks are now evaluated in a child of the global environment (#972).
* `@inheritParams` does a better job of munging links.
Links of the form `\link[=topic]{text}` are now automatically converted to
`\link[pkg:topic]{text}` when inherited from other packages (#979).
Internal `has_topic()` helper has a better implementation; this means that
links should no longer be munged unnecessarily (#973).
* `\example{}` escaping has been considerably simplified (#967), and is now
documented in `escape_example()`.
* In `\usage{}`, S3/S4 methods are no longer double-escaped (#976).
* Markdown tables with cells that contain multiple elements (e.g. text and code)
are now rendered correctly (#985).
* Markdown code blocks containing operators and other special syntax
(e.g. `function`, `if`, `+`) now converted to `\code{}` not `\verb{}` (#971).
# roxygen2 7.0.0
## New features
### New tags
* `@includeRmd {path.Rmd}` converts an `.Rmd`/`.md` file to `.Rd` and includes
it in the manual page. This allows sharing text between vignettes,
`README.Rmd`, and the documentation. See `vignette("rd")` for details (#902).
* `@order {n}` tag controls the order in which blocks are processed. You can
use it to override the usual ordering which proceeds from the top of
each file to the bottom. `@order 1` will be processed before `@order 2`,
and before any blocks that don't have an explicit order set (#863).
* `@exportS3Method` tag allows you to generate `S3method()` namespace
directives (note the different in capitalisation) (#796). Its primary use is
for "delayed" method registration, which allows you to define methods for
generics found in suggested packages (available in R 3.6 and greater).
For example,
```R
#' @exportS3Method package::generic
generic.foo <- function(x, ...) {
}
```
will generate
```
S3method(package::generic, foo)
```
(See [`vctrs::s3_register()`](https://vctrs.r-lib.org/reference/s3_register.html)
you need a version that works for earlier versions of R).
It also has a two argument form allows you generate arbitrary `S3method()`
directives:
```R
#' @exportS3Method generic class
NULL
```
```
S3method(generic, class)
```
* New `@returns` is an alias for `@return` (#952).
### R6
roxygen2 can now document R6 classes (#922). See `vignette("rd")` for details.
### Markdown improvements
* Rd comments (`%`) are now automatically escaped. You will need to replace any
existing uses of `\%` with `%` (#879).
* Markdown headings are supported in tags like `@description`, `@details`,
and `@return` (#907, #908). Level 1 headings create a new top-level
`\section{}`. Level 2 headings and below create nested `\subsections{}`.
* Markdown tables are converted to a `\tabular{}` macro (#290). roxygen2
supports the [GFM table syntax](https://github.github.com/gfm/#tables-extension-)
which looks like this:
```md
| foo | bar |
| --- | --- |
| baz | bim |
```
* Markdown code (``` `foofy` ```) is converted to to either `\code{}` or
`\verb{}`, depending on whether it not it parses as R code. This better
matches the description of `\code{}` and `\verb{}` macros, solves a certain
class of escaping problems, and should make it easier to include arbitrary
"code" snippets in documentation without causing Rd failures (#654).
* Markdown links can now contain formatting, e.g. `[*mean*][mean]` will now
generate `\link[=mean]{\emph{mean}}`.
* Use of unsupported markdown features (e.g. blockquotes, inline HTML,
and horizontal rules) generates informative error messages (#804).
### Default usage
* The default formatting for function usage that spans multiple lines has
now changed. Previously, the usage was wrapped to produce the smallest number
of lines, e.g.:
```R
parse_package(path = ".", env = env_package(path),
registry = default_tags(), global_options = list())
```
Now it is wrapped so that each argument gets its own line (#820):
```R
parse_package(
path = ".",
env = env_package(path),
registry = default_tags(),
global_options = list()
)
```
If you prefer the old behaviour you can put the following in your
`DESCRIPTION`:
```
Roxygen: list(old_usage = TRUE)
```
### Code loading
roxygen2 now provides three strategies for loading your code (#822):
* `load_pkgload()`, the default, uses [pkgload](https://github.com/r-lib/pkgload).
Compared to the previous release, this now automatically recompiles your
package if needed.
* `load_source()` attaches required packages and `source()`s all files in `R/`.
This is a cruder simulation of package loading than pkgload (and e.g. is
unreliable if you use S4 extensively), but it does not require that the
package be compiled. Use if the default strategy (used in roxygen2 6.1.0
and above) causes you grief.
* `load_installed()` assumes you have installed the package. This is best
used as part of a bigger automated workflow.
You can override the default either by calling (e.g.) `roxygenise(load_code = "source"))` or by setting the `load` option in your DESCRIPTION: `Roxygen: list(load = "source")`.
### Options
* As well as storing roxygen options in the `Roxygen` field of the
`DESCRIPTION` you can now also store them in `man/roxygen/meta.R` (#889).
The evaluation of this file should produce a named list that maps option
names to values.
* roxygen now also looks for templates in `man/roxygen/templates` (#888).
* New `rd_family_title` option: this should be a named list, and is used to
overrides the default "Other family: " prefix that `@family` generates.
For example, to override the prefix generated by `@family foo` place
`rd_family_title <- list(foo = "Custom prefix: ")` in
`man/roxygen/meta.R` (#830, @kevinushey).
## Breaking changes
* Rd comments (`%`) are automatically escaped in markdown formatted text.
This is a backward incompatible change because you will need to replace
existing uses of `\%` with `%` (#879).
* Using `@docType package` no longer automatically adds `-name`. Instead
document `_PACKAGE` to get all the defaults for package documentation, or
use `@name` to override the default file name.
* `@S3method` has been removed. It was deprecated in roxygen2 4.0.0
released 2014-05-02, over 5 years ago.
* Using the old `wrap` option will now trigger a warning, as hasn't worked
for quite some time. Suppress the error by deleting the option from your
`DESCRIPTION`.
### Extending roxygen2
The process for extending roxygen2 with new tags and new roclets has been completely overhauled, and is now documented in `vignette("extending")`. If you're one of the few people who have written a roxygen2 extension, this will break your code - but the documentation, object structure, and print methods are now so much better that I hope it's not too annoying! Because this interface is now documented, it will not change in the future without warning and a deprecation cycle.
If you have previously made a new roclet, the major changes are:
* The previously internal data structures used to represent blocks and tags
have been overhauled. They are now documented and stable. See `roxy_block()`
and `roxy_tag()` for details.
* `roclet_tags()` is no longer used; instead define a `roxy_tag_parse()` method.
For example, if you create a new `@mytag` tag, it will generate a class of
`roxy_tag_mytag`, and will be parsed by `roxy_tag_parse.roxy_tag_mytag()`
method. The method should return a new `roxy_tag()` object with the
`val` field set.
This means that the `registry` argument is no longer needed and has
been removed.
* `rd_section()` and `roxy_tag_rd()` are now exported so that you can more
easily extend `rd_roclet()` with your own tags that generate output in
`.Rd` files.
* `global_options` is no longer passed to all roclet methods. Instead, use
`roxy_meta_get()` to retrieve values stored in the options (#918).
* `tag_two_part()` and `tag_words()` are now simple functions, not function
factories.
* `tag_markdown_restricted()` has been removed because it did exactly the
same thing as `tag_markdown()`.
A big thanks goes to @mikldk for starting on the vignette and motivating me to make the extension process much more pleasant (#882).
## Bug fixes and minor improvements
* Empty roxygen2 lines at the start of a block are now silently removed (#710).
* Whitespace is automatically trimmed off the `RoxygenNote` field when
comparing the installed version of roxygen2 to the version used to
generate the documentation (#802).
* Files generated on Windows systems now retain their existing line endings, or
use unix-style line endings for new files (@jonthegeek, @jimhester, #840).
* roxygen2 now recognises fully qualified S4 functions like
`methods::setGeneric()`, `methods::setClass()` and `methods::setMethod()`
(#880).
* Package documentation now converts ORCIDs into a useful link (#721).
The package logo (if found at `man/images/logo.png`) is now scaled to 120px
wide (@peterdesmet, #834).
* Documenting an S4 method that has a `.local()` wrapper no longer fails with
an obscure error message (#847).
* Functions documented in `reexports` are now sorted alphabetically by
package (#765).
* `@describeIn` can now be used with any combination of function types
(#666, #848).
* `@description` and `@detail` tags are automatically generated from the
leading description block, and now have correct line numbers (#917).
* `@example` and `@examples` are interwoven in the order in which they
appear (#868).
* In `@examples`, escaped `'` and `"` in strings are no longer doubly escaped
(#873).
* `@family` automatically adds `()` when linking to functions (#815),
and print each link on its own line (to improve diffs).
* When `@inherit`ing from external documentation, `\link{foo}` links
are automatically transformed to `\link{package}{foo}` so that they work in
the generated documentation (#635). `\href{}` links in external inherited are
now inserted correctly (without additional `{}`) (#778).
* `@inherit`ing a a function with no arguments no longer throws a confusing
error message (#898).
* `@inheritDotParams` automatically ignores arguments that can't be inherited
through `...` because they are used by the current function (@mjskay, #885).
* `@inheritDotParams` includes link to function and wraps parameters
in `\code{}` (@halldc, #842).
* `@inheritDotParams` can be repeated to inherit dot docs from multiple
functions (@gustavdelius, #767).
* `@inheritDotParams` avoids multiple `...` arguments (@gustavdelius, #857).
* `@inheritParams` ignores leading dots when comparing argument names (#862).
* `@inheritParams` warns if there are no parameters that require
documentation (#836).
* `@param` containing only whitespace gives a clear warning message (#869).
* Multiple `@usage` statements in a single block now generate a warning.
Previously, the first was used without a warning.
# roxygen2 6.1.1
* Now specifically imports recent version of desc package (>= 1.2.0) to
fix various parsing issues (@crsh, #773, #777, #779). Multi-line DESCRIPTION
collate directives now correctly parsed on windows (@brodieG, #790).
* `roxygenise()` no longer recompiles packages containing src code (#784).
* `roxygenise()` now stops with an informative error message when run in a
directory that's not the package root (@mikmart, #704).
# roxygen2 6.1.0
## New features
* The `NAMESPACE` roclet now works in two passes - it first generates the
`NAMESPACE` containing only import directives because this can be generated
without evaluating the code in the package. This alleviates a problem
where it was previously possible to get into a state that you could only
get out of by carefully editing the `NAMESPACE` by hand (#372).
* `@evalRd foo()` evaluates `foo()` defined in the package namespace and inserts
the results into the current block (#645). The code should return a character
vector with one entry for each line (and they should not start with `#'`).
There are two small limitations to the current implementation:
1. The generated roxygen will not affect the `@md`/`@noMd` status
2. `@evalRd` does not work inside templates.
* `@evalNamespace` does for `NAMESPACE` what `@evalRd` does for Rd files:
you give it R code that produces a literal entry in `NAMESPACE` when
run. This should make it easier to export functions that are generated by
other functions in your package (#531, @egnha).
* `@inherits` can now inherit examples (#588).
* `vignette("rd")` received a thorough updating for current best-practices.
The vignette still needs more work so pull requests are greatly appreciated
(#650).
* `roxygenise()` uses `pkgload::load_all()` instead of a home grown solution
to simulate package loading (this is needed because roxygen2 uses run-time
information to generate the documentation). This should reduce S4 related
problems and ensures that `devtools::document()` and `roxygenise()` always
have exactly the same behaviour (#568, #595).
* If an inherited section cannot be found, the warning contains the help
page from which that section was requested (#732, @krlmlr).
* roxygen2 now always reads and writes using UTF-8 encoding. If used with a
package that does not have `Encoding: UTF-8` in the DESCRIPTION, you'll
now get a warning (#564, #592).
## Extension API
* Roxygen blocks now have an official structure as encoded in
`roxy_block()`. It is a named list containing the tags with attributes
providing other metadata.
* The `parsed` argument to `roclet_process()` have been replaced with
separate `blocks` and `env` arguments.
* New `roclet_preprocess()` generic makes it possible for roclets to perform
actions before code is evaluated.
* `parse_package()`, `parse_file()` and `parse_code()` provide an exported API
that allows you to use roxygen's parsing code independently of creating
roclets.
## Minor improvements and bug fixes
* All tags (including `@alias`) are now de-duplicated and consistently sorted.
This reduces spurious diffs (#586, @flying-sheep).
* `@concept` now generates one `\concept` per tag (#611).
* The default `@description` (i.e. the title) is now added much later in the
process. That means that `@inherit description` now works when you have
specified a title for the inheritor (#629) and the default description
is slightly nicer when merging multiple blocks.
* `@family` automatically adds its value to concepts (#611).
* `@inherits`: The mechanism for extracting inherited Rd does a better job of
preserving escapes (#624)
* Empty `.Rbuildignore` now handled correctly (#576).
* Stricter regular expression ensures only files ending with `.R` or `.r` are
parsed for roxygen comments (#625).
* Objects with names starting with a dot are now by default documented in
files with prefix 'dot-'.
* Roclets can now access global options as designed. This allows templates to
use markdown formatting if set globally (#594).
* You can now autogenerate package documentation even if you don't have
`Authors@R` (#606).
* Multiple given and/or family names are now supported in the
`Authors@R` field of the DESCRIPTION file (#672, @sgibb).
* If a package logo exists (`man/figures/logo.png`) it will be automatically
included in generated package docs (#609).
* Usage for data objects now correctly generated, avoiding double escaping
other components of usage (#562).
* Improvements to markdown translation:
* Code in link text is now properly rendered as code (#620, @egnha).
* Whitespace between words in link text is now preserved as single
space for links of the form `[text][fcn]` and `[text](URL)`
(#628, #754, #760, @egnha and @jennybc).
* `%` in inline code (#640), code blocks (@nteetor, #699) and
links (#724) is now automatically escaped.
* Parsing of markdown links has been tweaked to reduce false positives
(#555). If you still get a false positive, you can now put `\\` in front
of the `[` to avoid it being converted to a link (#720). Links can no
longer be followed by `{` to avoid spurious matches to Rd commands like
`\Sexpr{}`.
* Unsupported markdown features now generate a mildly helpful warning
instead of throwing an utterly useless error (#560).
* `person()` now supports all
[MARC Relator](https://www.loc.gov/marc/relators/relaterm.html) role codes
(#662, @publicus).
* `topic_add_usage()` now outputs formatted "Usage" section with max
width of 80 characters thanks to a now more flexible `wrap_string()`
(@JoshOBrien, #719).
# roxygen2 6.0.1
* Allowing empty lines in .Rbuildignore. Previously, empty lines caused all
files to be ignored. (#572, @jakob-r)
* Automatically generating a usage section for an infix function containing "<-"
no longer removes "<-" from the function name (#554).
# roxygen2 6.0.0
## Markdown
* Most fields can now be written using Markdown markup instead of the
traditional Rd language. You can turn on Markdown globally by adding
`Roxygen: list(markdown = TRUE)` to `DESCRIPTION`. The `@md` / `@noMd`
tags turn Markdown parsing on / off for the given block. See
`vignette("markdown")` for more details (#364, #431, #499, #506, #507),
by @gaborcsardi
## Improved inheritance
* New `@inheritDotParams` allows you to automatically generate parameter
documentation for `...` for the common case where you pass `...` on to
another function (#512). Because you often override some arguments, it
comes with a flexible specification for argument selection:
* `@inheritDotParams foo` takes all parameters from `foo()`
* `@inheritDotParams foo a b e:h` takes parameters `a`, `b`, and all
parameters between `e` and `h`
* `@inheritDotParams foo -x -y` takes all parameters except for `x` and `y`.
The documentation generated is similar to the style used in `?plot`
and will eventually be incorporated in to RStudio's autocomplete.
* New `@inherit` generalises `@inheritParams`, and allows to you inherit
parameters, return, references, title, description, details, sections, and
seealso. The default `@inherit my_fun` will inherit all, you can document
an object entirely by specifying only the `@inherit` tag. Alternatively,
you can select specific tags to inherit with `@inherit my_fun return params`
(#384).
* New `@inheritSection fun title` allows you to inherit the contents of
a single section from another topic (#513).
* `@inheritParams` now works recursively, so that you can inherit parameters
from a function that inherited its parameters from somewhere else. It
also better handles `\dots` as an alias for `...` (#504).
## Minor improvements and bug fixes
### Tags
* `@aliases` are no longer sorted alphabetically, but instead match the
order of their usage. This gives you more control in pkgdown.
* `@describeIn` now escapes special characters in function names (#450).
* `@family` see alsos are added in the same order they appear, not
alphabetically (#315). Fixed an issue where `.`s were sometimes added
between words within a `@family` tag (#477, @kevinushey).
* `@author` is rendered after `@seealso`.
* `@example` gives a nice warning message if you accidentally use it instead
of `@examples` (#494). Multiple `@examples` sections are merged (#472, @krlmlr).
* Roxygen will no longer write out topics that don't have a name or title,
and will instead generate a warning. This makes it easier to detect if
you've accidentally used `@rdname` with an incorrect value (#474).
### S3
* Non-primitive, internal S3 generics (e.g. 'rbind', 'cbind') are now properly
detected as S3 generics. (#488, @kevinushey)
* Ensure that `functions` with S3 class are still treated as functions (#455).
* S3 method declarations via `R.methodS3::setMethodS3()` and function
declarations via `R.oo::setConstructorS3()` are now supported
(@HenrikBengtsson, #525).
### S4
* You can now document `setClassUnion()`s (#514).
* The default alias for S4 method now re-adds trailing ANY signatures
that are sometimes dropped (#460).
* Back references are now wrapped over multiple lines, if long
(#493, @LiNk-NY).
### Other
* `"_PACKAGE"` documentation now generates a default `@seealso` combining
the `URL` and `BugReport` fields, and a default `@author` field generated
from the `Authors@R` field (#527). It now works from `roxygenise()`; before
it only worked from `devtools::document()` (#439, @krlmlr).
* Manually created `NAMESPACE` or documentation files are never overwritten,
even if using `roxygen2` for the first time (@krlmlr, #436).
* Changes to DESCRIPTION (i.e. `Collate:` and `RoxygenNote`) now use
the desc package. This will minimise spurious changes (#430).
* `default_data_format()` has been renamed to `object_format()`.
* New `roclet_find()` provides a more flexible way to specify roclets:
as roclet name (e.g. "rd_roclet"), in an package ("foo::roclet_bar"),
or with options ("foo::roclet_bar(baz = TRUE)").
* The usage of replacement functions uses non-breaking spaces so that `<-`
will never get put on its own line (#484).
* Roxygen now parses nonASCII documentation correctly (as long as UTF-8
encoded or specified Encoding in DESCRIPTION) (#532, @shrektan),
and ignores files listed in `.Rbuildignore` (#446, @fmichonneau).
## Extending roxygen2
* Deprecated `register.preref.parser()` and `register.preref.parsers()`
have been removed. `register_tags()` has also been removed in favour of
a new `roclet_tags()` generic.
* `roclet()` (the constructor), `roclet_tags()`, `roclet_process()`
`roclet_output()`, `roc_clean()` and now exported making it possible
to create roclets in other packages. Helper functions `roxy_tag()` and
`roxy_tag_warning()` are also exported.
* `new_roclet()` is no longer exported - use `roclet()` instead.
# roxygen2 5.0.1
* Use `ls()`, not `names()` to list elements of environment: fixes R 3.1.0
incompatibility (#422, @kevinushey).
* `@export` again allows trailing new line (#415).
* Fixed bug in `@noRd`, where usage would cause error (#418).
# roxygen2 5.0.0
## New features
* Roxygen now records its version in a single place: the `RoxygenNote`
field in the `DESCRIPTION` (#338). This will be the last time an roxygen2
upgrade changes every file in `man/`.
* You can now easily re-export functions that you've imported from another
package:
```R
#' @export
magrittr::`%>%`
```
All imported-and-re-exported functions will be documented in the same
file (`rexports.Rd`), containing a brief description and links to the
original documentation (#376).
* You can more easily generate package documentation by documenting the
special string "_PACKAGE" (@krlmlr, #349):
```R
#' @details Details
"_PACKAGE"
```
The title and description will be automatically filled in from the
`DESCRIPTION`.
* New tags `@rawRd` and `@rawNamespace` allow you to insert raw (unescaped)
in Rd and the `NAMESPACE` (this is useful for conditional imports).
`@evalRd()` is similar, but instead of literal Rd, you give it R code that
produces literal Rd code when run. This should make it easier to experiment
with new types of output (#385).
* roxygen2 now parses the source code files in the order specified in the
`Collate` field in `DESCRIPTION`. This improves the ordering of the generated
documentation when using `@describeIn` and/or `@rdname` split across several
`.R` files, as often happens when working with S4 (#323, #324).
## Minor features and bug fixes
* The contents of documented functions are now also parsed for roxygen comments.
This allows, e.g., documenting a parameter's type close to where this type is
checked, or documenting implementation details close to the source, and
simplifies future extensions such as the documentation of R6 classes
(#397, @krlmlr).
* Data objects get a simpler default `@format` that describes only the
object's class and dimensions. The former default, generated by generated by
`str()`, didn't usually produce useful output and was quite slow. The new S3
generic `default_data_format()` generates the format and can be overridden to
generate a custom format (#410, @krlmlr).
* The roxygen parsers has been completely rewritten in C++ (#295). This gives a
nice performance boost and gives:
* Better error messages: you now get the exact the line number of the
tag, not just the start of the block.
* The parser has been simplified a little: tags now must always start
on a new line. This is recommended practice anyway, and it means
that escaping inline `@` (with `@@`) is now optional. (#235)
* Unknown tags now emit a warning, rather than an error.
* `@examples` no longer complains about non-matching braces inside
strings (#329).
* `@family` now cross-links each manual page only once, instead of linking
to all aliases (@gaborcsardi, #283, #367).
* The special `@include` parser has also been rewritten in C++, giving
a performance boost for larger packages (#401). This is particularly
important because it's also called from `devtools::load_all()`.
Additionally, a space before `@include` is no longer necessary
(@krlmlr, #342).
* `@inheritParams foo::bar` ensures that `%` remains escaped (#313).
* If you document multiple arguments with one `@param`, (e.g. `@param a,b,c`)
each parameter will get a space after it so it can be wrapped in the
generated Rd file (#373).
* `@section`s with identical titles are now merged together, just like
`@description` and `@details`. This is useful in conjunction with the
`@rdname` tag. (@krlmlr, #300).
* Automatic `@usage` is now correctly generated for functions with string
arguments containing `"\""` (#265).
* `load_options()` is now exported so `devtools::document()` doesn't have to
run `update_collate()` twice (#395).
* `update_collate()` only rewrites the `Collate` entry in the DESCRIPTION file
when it changes (#325, #723).
* An empty `NAMESPACE` file is written if it is maintained by `roxygen2`
(@krlmlr, #348).
* Data that is not lazy-loaded can be documented (@krlmlr, #390).
## Internal changes
* `register.preref.parser()` and `register.preref.parsers()` have been
deprecated - please use `register_tags()` instead.
* Parser callbacks registered with `register_tags()` are now called for fields
parsed from the "introduction" (the text before the first tag)
(@gaborcsardi, #370).
# roxygen2 4.1.1
* Formatting of the `Authors@R` field in the DESCRIPTION file is now retained
(@jranke, #330).
* The collate roclet falls back to `base::strwrap()` when generating the
collate field. This makes roxygen2 compatible with the next version of
stringr.
* New "vignette" roclet. This vignette automatically rebuilds all out of date
vignettes (#314).