Benchmark metrics: Explain what these values are in more detail

[maurolepore]

(Extracted from https://github.com/2DegreesInvesting/r2dii.analysis/pull/104#issue-435751759)

[Regarding] the benchmark output of target_market_share() (...) I think that these metric names are evocative and descriptive, however I think it would make sense to explain what these values are in a little more detail, where do you think the best place to host this is? I think we had briefly discussed the idea of a data_dictionary for the output, maybe this is the time to start thinking about that? -- @jdhoffa

AB#9905

[maurolepore]

If what we need to document is the output of ...

• ... a single function, I would document it in the @retrurn section of that function.
• ... multiple functions, I would consider documenting the multiple functions together (e.g. via @rdname); or document them separately but DRY the shared elements of @return via @template, or as we did with r2dii.match/vignettes/_validate-matches.md (that is #' @includeRmd vignettes/_validate-matches.md).

Instead of what I wrote above, it would be nice to document the output of all functions in a data_dictionary -- as we do in r2dii.data -- but this seems beyond the first release.

[maurolepore]

@jdhoffa is this something we plan before or after the initial release?

[jdhoffa]

I would say after actually, or at least after the internal review from colleagues to ensure our metric names are adequate and make sense

[jdhoffa]

Relates to #269