Document how j results are combined with by via rbindlist (issue #7643)

[mahjabinoyshi]

This PR updates the ?data.table documentation to clarify how per‑group j results are combined when by is used.

The new paragraph explains that j is evaluated once per group and the results are bound row‑wise using rbindlist with use.names = FALSE, so columns are matched by position and the first group’s column names are kept. This makes the behavior in cases like #7643 explicit.

A small test in tests/by-rbindlist-use-names-false.R is given to capture the current behavior so the documentation and implementation stay in sync.

Closes #7643.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.02%. Comparing base (67e7840) to head (47fade6).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #7651   +/-   ##
=======================================
  Coverage   99.02%   99.02%           
=======================================
  Files          87       87           
  Lines       16897    16897           
=======================================
  Hits        16733    16733           
  Misses        164      164           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jangorecki]

Why not to give explanation in rbindlist a d just refer that by uses rbindlist internally?

?data.table is already so big

[mahjabinoyshi]

@jangorecki Thanks for the feedback!

I’m happy to move most of the explanation to ?rbindlist instead.
my plan is:

1)In ?data.table, shorten the new text to something like:
When by is supplied, j is evaluated once per group and the per‑group
results are combined row‑wise using rbindlist (see ?rbindlist for details
of how columns and names are handled).
2)Add a paragraph to ?rbindlist documenting the use.names = FALSE behavior
and how it affects column names when items have different names in the same
positions.

Will it be okay?

[tdhock]

this text is too long, please shorten.
also please remove line breaks (diff should show 1 line).
also please find a more appropriate place to put it on that man page (near discussion of by arg?)

[tdhock]

and please remove test case

[mahjabinoyshi]

@tdhock I’ve updated the PR to shorten the by documentation, kept the new sentence within the by argument section, and removed the test case as requested.

[tdhock]

there are still line breaks, please remove.

Also I think this should be moved up closer to the sentence that describes group order.

by: Column names are seen as if they are variables (as in 'j' when 'with=TRUE'). The 'data.table' is then grouped by the 'by' and 'j' is evaluated within each group. The order of the rows within each group is preserved, as is the order of the groups. The results are combined using \code{\link{rbindlist}}.