sunjay
commented
6 years ago Hi! Thanks for taking the time to write this example! Documentation is an incredibly important part of this project and I really appreciate you being willing to work on it! :smile:
If you haven't already, I definitely suggest going through the resources linked to in the original issue. In particular, I would like to point you to this part of the Rust API Guidelines:
The purpose of an example is not always to show how to use the item. Readers can be expected to understand how to invoke functions, match on enums, and other fundamental tasks. Rather, an example is often intended to show why someone would want to use the item.
I think your example does a really good job of showing how to invoke turn_towards, and I would really like to see it become an example that shows people why and in which circumstances they could use it. We don't do this perfectly in all turtle examples yet, but it is something I am aiming for in the final release.
One example of where I think we do this well is in the set_speed method. Our example for Moving Instantly is great because it demonstrates the feature and tells the reader what it is useful for.
Notice that both the example code and the accompanying text are very important there.
We also have more elaborate examples with screenshots of the output. That is not strictly necessary for something like turn_towards.
I encourage you to take some time and think about turn_towards and what it is useful for. Then, try to come up with an example which illustrates that in a way where the reader really understands what they can do with it. Once someone understands how to use something, they start to get all kinds of ideas about where it could come in handy in their projects.
If any of this sounds daunting to you, I am here for you! Please don't hesitate to ask me questions or discuss possible examples with me. There is no shame in trying a few out and getting feedback. :smile:
Finally, just one small comment about your code: I think it is okay to just add the example to the documentation without duplicating it in the examples/ directory. Unless there is some other reason for that, I think the new example is good in one place.
scompo
Added an example to the documentation of
Turtle::turn_towards, see #85. Also added the same example in the examples folder. Hope it's fine.Mauro