docs: Hydro language docs

[jhellerstein]

We need a doc with legal Hydro operators.

• Generate a landing page in the Hydro docs for Streams, Singletons and Optionals
• Update each method for those with Rust docs

[shadaj]

I think the way we should think about this is not as "operators" or a "grammar". It's just a Rust API, the same as tokio or Rust iterators (in particular, the "operators" available vary wildly based on type context). So I don't think it's particularly feasible to auto-gen a page with all the operators, instead we should flesh out the Rustdoc and point to https://hydro.run/rustdoc/hydro_lang/stream/struct.Stream. And also have human-written doc pages for the different collections type to provide more conceptual intuition.

[jhellerstein]

I'm fine not calling it a grammar, you're right. But I absolutely think we should have a single page in the docs for all the hydro operators (the API). I refer to the DFIR operators doc all the time.

…

On Tue, Jan 7, 2025 at 11:32 AM Shadaj Laddad ***@***.***> wrote: I think the way we should think about this is not as "operators" or a "grammar". It's *just* a Rust API, the same as tokio or Rust iterators (in particular, the "operators" available vary wildly based on type context). So I don't think it's particularly feasible to auto-gen a page with all the operators, instead we should flesh out the Rustdoc and point to https://hydro.run/rustdoc/hydro_lang/stream/struct.Stream. And also have human-written doc pages for the different collections type to provide more conceptual intuition. — Reply to this email directly, view it on GitHub <#1633 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC54QKQNKRUIPT732JWEXD2JQTURAVCNFSM6AAAAABUYD3NMGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDKNZWGA3TIOBZGE> . You are receiving this because you were assigned.Message ID: ***@***.***>

[shadaj]

I think the tricky difference is unlike DFIR we have streams vs singletons vs optionals which use independent sets of operators. Also unlike DFIR we can use standard Rust tooling for documenting APIs, so I'd prefer to avoid redundancy and instead have a shortcut to this on the website.

[jhellerstein]

So the key entry points are the following?

• https://hydro.run/rustdoc/hydro_lang/stream/struct.Stream
• https://hydro.run/rustdoc/hydro_lang/singleton/struct.Singleton
• https://hydro.run/rustdoc/hydro_lang/optional/struct.Optional

We need a landing page for those and then rustdocs for the operators.

[MingweiSamuel]

I agree that it would be nice to have a concise index linking to those three pages and listing/linking all the corresponding methods