search

microsoft / yardl

Tooling for streaming instrument data
https://microsoft.github.io/yardl/
MIT License
30 stars 5 forks source link

doc on enums unclear #68

Closed KrisThielemans closed 11 months ago

KrisThielemans commented 1 year ago

https://microsoft.github.io/yardl/reference/binary.html#enums-and-flags has a typo "properly" , but it is unclear how the base type would be defined. A link to somewhere else?

johnstairs commented 1 year ago

There are language-specific guides here and here. We link to them at the top of this document perhaps?

johnstairs commented 1 year ago

I guess the encoding format reference is written with the assumption that the Yardl language guide was already read, but of course that is not necessarily the case. We could link in each section of this page to the corresponding sections in the Python and C++ docs. What do you think?

KrisThielemans commented 1 year ago

Choosing where to put relevant bits of the documentation is always a nightmare. I like writing things in 1 place, and then linking to it from other places. Other people get fed-up that they have to follow those links all the time... Not sure what the best strategy is!

In any case, the text in those "language specific" links is virtually identical, except the very last paragraph on representation in Python and C++. So, my feeling is that text should be in the "how to write the yardl file" doc, the C++/Python doc should like to the yardl-section, and the binary-encoding doc as well.

But up to you.