doc: Document .RData handoff points in core workflow functions

[S1DDHEY]

Description

This draft PR adds documentation for .RData handoff points in core PEcAn workflow functions. It focuses on improving @returnand @details sections to clarify what objects are written to disk and how they are used by downstream steps.

This work is part 1 of my pre-GSoC prep for the modularity project.

Motivation and Context

Review Time Estimate

• Immediately
• Within one week
• When possible

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

• My change requires a change to the documentation.
• My name is in the list of CITATION.cff
• I agree that PEcAn Project may distribute my contribution under any or all of
  • the same license as the existing code,
  • and/or the BSD 3-clause license.
• I have updated the CHANGELOG.md.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[S1DDHEY]

The current CI check fails because of multiple .Rd files being out of sync, not sure why there are so many of them as I have only made changes in very few files.

[infotroph]

@S1DDHEY Looks like declaring markdown=TRUE for the whole DB package made Roxygen change something in ~every Rd file.

Adopting Markdown across all our Roxygen docs is a worthy but low-priority goal, so if you're up for reviewing all the changes and confirming the changes are desirable / editing as needed, go for it.

If you'd rather not take that on in this PR, you can take markdown = TRUE out of DESCRIPTION and instead opt in the pages you edited by including #' @md somewhere in each Roxygen block that you want interpreted as Markdown.

[S1DDHEY]

@infotroph Thank you for the clarification, for this PR I'd just revert the DESCRIPTION file changes and will proceed by adding the @md tag for all the changes I did.

[S1DDHEY]

@mdietze let me know if any changes are needed for this one, I'll add the .Rd files accordingly.

[mdietze]

Rather than giving a warning about this, which I don't think represents the desired behavior, why don't we just fix it?

[S1DDHEY]

done, removed this part

pecan/base/db/R/get.trait.data.pft.R

Lines 30 to 32 in ae934e8

	## Remove old files. Clean up.
	old.files <- list.files(path = pft$outdir, full.names = TRUE, include.dirs = FALSE)
	file.remove(old.files)

[mdietze]

I'm not sure this is true. Doesn't the posterior id point you to the right folder if you query BETY?

[S1DDHEY]

The posteriorid in the return value does serve as an indirect path to the output files via BETY's dbfiles table (e.g.

pecan/base/db/R/get.trait.data.pft.R

Lines 101 to 102 in ae934e8

	files <- dbfile.check(type = "Posterior", container.id = pft$posteriorid, con = dbcon,
	return.all = TRUE)

is used to locate exactly these files). Updated the @return