Merge sections with identical title

[krlmlr]

If two files have entries @section OBTW and @rdname base, the file base.Rd contains two sections titled "OBTW". On the other hand, the "Description" and "Detail" sections are merged. Wouldn't it be a good idea (and feasible) to also merge sections with identical names?

Example package: https://github.com/krlmlr/section.merge.test

Also, the contents are generated in the order of the input file names. In the example above, it's a < b < base, but base.R is the "main" source file for base.Rd. Perhaps the contents that come from the "main" input file (if there is one) should come before the other contents?

[hadley]

Yes, merging sections with identical titles would be good, and I'd be happy to review a pull request.

Merging them in a better order is going to be hard, because it'll involve a topological sort. I'd also be happy to review a (separate) PR for that, if you're game!

[krlmlr]

Basic (unordered) functionality is now ready for review.

For @rdname, I think the best order would be first the contents of the "main" item (that defines the .Rd file) followed by all other items in their natural order. Can you think of an example that actually involves a more complicated topological sort?

[hadley]

I'm going to hold of on merging this for this release, just because I need to get roxygen2 out today, and haven't had a chance to properly review this

[Geoff99]

Not sure if it is exactly what you are looking for in terms of the natural order for the merged sections, but pull request #324, relating to issue #323, would ensure that roxygen2 parses the files in collate (as opposed to alphabetical) order, and hence also generates the documentation in that order.

If not it might at least give a low effort way of specifying the natural order via @include tags.