docs: Improve min_st_separators() documentation

[szhorvat]

@maelle Is this the best way to comment on examples? Can we comment using normal text that includes math instead of writing code comments? If yes, can you push to this branch and demonstrate?

[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 PR was merged using Aviator.

---

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.

[maelle]

Good question!

We can't have maths in example but a workaround would be to create an arbitrary section using R Markdown support. The code in the code chunk is evaluated every time the document() function is run,

• which seems fine as far as time is concerned as this is fast code apparently;
• which made me add the same code as a test case.

https://roxygen2.r-lib.org/articles/rd-formatting.html#code-chunks

Note that the section name is currently really bad. 😁

[szhorvat]

Thank you!

[szhorvat]

A problem is that every time we re-generate docs, something changes:

Should we do something about this?

Perhaps we should just go with the original code comment version? The math is actually not that important for this specific example.

[krlmlr]

In the tests, we have local_igraph_options(print.id = FALSE) to inhibit this, but I'm not sure what's the best way to use this with a roxygen2 example.

@maelle: Can you help please?

[maelle]

Probably not the best solution as this is an unexported function 🤪 (so especially confusing for users) I need to make it work to put the call in a separate chunk (using the .in argument), will try again later this week.

[szhorvat]

Let's just add the comments as an actual code comment, problem solved. Agreed?

I would rather not add distracting code to an example which is making an important point about how a function behaves.

[maelle]

I'll experiment with a knitr hook to modify the output without a comment. I fear the comment is distracting too.