You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
ehuss's preference: Yes, I think illustrations are very helpful.
Consider that some readers will skip or skim the text and look at the code first.
How often should there be examples? Are there any guidelines for when they should and should not be used?
If we have a separate testsuite, can some of those examples be offloaded to the testsuite?
That is, instead of showing some examples inline, just allow the user to somehow view the testsuite for a specific rule.
Should there be naming conventions, such as avoiding nonsense terms like foo/bar/baz, and using realistic terms instead.
ehuss's preference: I would encourage not using nonsense terms, and try to use names that are illustrative of the concept whenever possible (example).
Should the examples prefer to be realistic of what a user would actually write?
That can be difficult, since that often requires longer examples. Unrealistic or trivial examples can be confusing.
Are there guidelines for balancing length versus clarity? There are times when to illustrate some concept, it may require a significant amount of code. At what point is too much? mdBook supports hiding irrelevant portions of code, but that has limitations.
Should example code be inline within the text, or outline (like TRPL) and use includes? Inline is easier to author, outline is easier to test.
If using rustdoc (mdbook test) to test, then there should be guidelines on using tags like no_run, ignore, E errors, etc.
Should inline code samples be tested with mdbook test, or via a separate test infrastructure? mdbook test is very easy to use, and makes it easy to see the code in the source text. However, it is very limited in its capabilities.
ehuss's preference: I think we should (eventually) invest in a test infrastructure using compiletest or ui_test. We can perhaps have some kind of hybrid inline/outline model, but I don't know what that might look like.
Should examples be formatted with rustfmt?
Any non-default options?
The text was updated successfully, but these errors were encountered:
The following are some questions about including code samples in the text.
See https://github.com/rust-lang/reference/blob/master/STYLE.md#code-examples for the reference guide.
That is, instead of showing some examples inline, just allow the user to somehow view the testsuite for a specific rule.
That can be difficult, since that often requires longer examples. Unrealistic or trivial examples can be confusing.
mdbook test
) to test, then there should be guidelines on using tags likeno_run
,ignore
,E
errors, etc.mdbook test
, or via a separate test infrastructure?mdbook test
is very easy to use, and makes it easy to see the code in the source text. However, it is very limited in its capabilities.The text was updated successfully, but these errors were encountered: