docs: better describe output of all_shortest_paths()

[maelle]

Fix #1029

@szhorvat I'll need your help.

[aviator-app]

Current Aviator status

Aviator will automatically update this comment as the status of the PR changes.
Comment /aviator refresh to force Aviator to re-examine your PR (or learn about other /aviator commands).

This pull request is currently open (not queued).

How to merge

To merge this PR, comment /aviator merge or add the mergequeue label.

---

See the real-time status of this PR on the Aviator webapp.

Use the Aviator Chrome Extension to see the status of your PR within GitHub.

[szhorvat]

$res is for backwards compatibility. It is the same as $vpath. It is effectively deprecated. The deprecation should be made explicit, and it should be removed soon.

[krlmlr]

@maelle: Should this be part of the upcoming 2.1.3?

[maelle]

@krlmlr @szhorvat suggests deprecated res. For this we'd need #1576 I'd be curious to see you add this during a hackathon so I have a better chance of doing it myself another time.

[krlmlr]

Thanks!

[krlmlr]

Do we need \describe{} here? See https://developer.r-project.org/parseRd.pdf .

Yes, in R documentation (.Rd) files, you need to use \describe{} if you want to use \item{}{}.

Explanation:

• \describe{} is used to create a description list in R documentation.
• \item{}{} defines individual list items, where the first argument is the term being described, and the second argument is its description.

Example:

\describe{
  \item{param1}{This is the first parameter description.}
  \item{param2}{This is the second parameter description.}
}

Alternative:

• If you don’t need a term-description list and just want bullet points, you can use \itemize{} instead:

  \itemize{
    \item First bullet point.
    \item Second bullet point.
  }

So, yes, \describe{} is required for \item{}{} in .Rd files.

[krlmlr]

@maelle: Do you want to take another stab?