[datatable-help] suggestion for transform.data.table.Rd

[G See]

It was not clear to me from the help page when I should use
`transform` or `within` instead of `:=`.

May I suggest copying the following comment (found in data.table.R) to
the help page?

# `within` and other similar functions in data.table are
# not just provided for users who expect them to work, or
# prefer syntax they're used to, but for non-data.table-aware
# packages to retain keys (for example). Hopefully users and
# code will use the faster data.table syntax in time.

Also, the examples section of ?transform.data.table has the following
commented out "example"

    # dt[, transform, c = max(b), by="a"]  # like "ave"

If run, this will give an error
    Error in `[.data.table`(dt, , transform, c = max(b), by = "a") :
      unused argument(s) (c = max(b))

Based on test 104, I think that should be changed to

    dt[, transform(.SD, c=max(b)), by="a"]

Best,
Garrett