Mention code generation in README - #30
Conversation
44632c5 to
b63f52d
Compare
|
@banchan86 Removed the fixes clause so we can consider providing an in-line example in a follow-up PR. |
glopesdev
left a comment
There was a problem hiding this comment.
Thanks for picking this up, and for explaining why you left the examples out. I agree with that call, though for a different reason than duplication, which I come to below.
Approving as it stands. Both points below are additive, so rather than hold this up I will fold them into a follow-up, along with a couple of unrelated readme items.
I would like to keep "interfacing with" in the description, and will restore it in the follow-up. The Description property in src/Harp.Toolkit/Harp.Toolkit.csproj and the GitHub repository description both read "A tool for inspecting, updating and interfacing with Harp devices from the command-line", and the package description renders directly above the readme on the package page, so dropping the phrase here makes the two disagree. The tool does still interface with devices, through list, --port and update, and that surface is about to grow considerably. The pending #16 adds a benchmark and compliance suite that exercises the core registers against a live device, validates a device against its own generated interface, and measures clock alignment and PPS synchronization, so device interfacing is set to become one of the larger parts of what this tool does. Keeping all three verbs also avoids using "interface" in two senses in one sentence:
Tool for inspecting, updating and interfacing with Harp devices, with automatic firmware and interface code generation.
On the one-liner example, I would keep it out of the numbered list and add a short section instead. The Getting Started list is a single sequential walkthrough for someone holding a device who wants to inspect or update it, and every step from 3 onwards assumes a serial port. A code generation step would assume a device.yml instead, so the reader of step 6 and the reader of a generation step are different people. The one-liner is also not self-sufficient, since it needs a device.yml already present in the working directory.
A dedicated section solves both, and is more discoverable than a clause in the description.
I think mentioning it in the description and linking to the code generation article might be enough. I left out the one-liners from the "Getting Started" examples because they're duplicated in that article, and we probably don't want consumers stumbling upon them anyway.