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.

[jangorecki]

What about keeping addition to ?data.table minimal and just refer to rbindlist section?

[tdhock]

please look at Files changed tab before asking for review, to make sure there are no irrelevant diff lines.