Design strategy discussion: documentation of language bindings

[lgritz]

As the first PRs are close to merging for C bindings (#2748), with the goal of also using this as a stepping stone to Rust bindings, I'm curious about your thoughts on how we should document this as it gets closer to completion.

Currently/previously, there is only C++ and Python. In the current docs, each major class gets a separate, extremely detailed chapter describing the C++ intertwined with discussion of the concepts/functionality. And then there is one separate chapter describing the Python bindings, recapitulating the C++ chapters but as shorter sections with only very brief descriptions. It's assumed that the C++ chapters are the primary documentation, and here we just quickly lay out what each Python call looks like.

Chapter: ImageInput
    Section: conceptual info
    Section: recipes for common tasks
    Section: ImageInput class reference
          - create()
               explanation
               parameters
               example in C++
          - read_scanline()
               explanation
               parameters
               example in C++
          ...
Chapter: ImageOutput
      ...
Chapter: ImageBuf
...
Chapter: Python Bindings
      Section: ImageInput
          - example of a use recipe in python
          - create() [very brief]
          - read_scanlines() [very brief]
      Section: ImageOutput
     ...

We could aim to continue this pattern -- adding a single additional chapter on C and a single chapter on Rust that are just catalogs of the C and Rust entry points with the briefest of descriptions, and only longer exposition when it's necessary to explain in detail how things differ from C++.

Chapter: ImageInput
Chapter: ImageOutput
Chapter: ImageBuf
...
Chapter: Python Bindings
    ...
Chapter: C Bindings
    [similar organization to Python Bindings chapter]
Chapter: Rust Bindings
    [similar organization to Python Bindings chapter]

Another potential way to organize the docs is not to have separate chapters for Python, C, and Rust at all, but rather to make the the main chapters that describe major C++ classes, each have subsections at the end of those chapters cataloging the equivalent Python, C, and Rust (again, as briefly as possible, with exposition only for how they differ from C++).

Chapter: ImageInput
    Section: conceptual info
    Section: recipes for common tasks
          [mostly C++ but some examples showing equivalent in C, Python, Rust]
    Section: ImageInput class reference in C++
          - read_scanline()
               explanation
               parameters
          - ... rest of API calls ...
    Section: ImageInput in Python
    Section: ImageInput in C
    Section: ImageInput in Rust
Chapter: ImageOutput
      ...
Chapter: ImageBuf
...
[ no separate chapters just for language bindings ]

And yet another way is that we dispense with even separate subsections, and just describe -- in each individual API call or class description -- what the call to that functionality looks like in each of the language bindings.

Chapter: ImageInput
    Section: conceptual info
    Section: recipes for common tasks
          [each shows how its done in C++, C, Python, Rust]
    Section: ImageInput class reference
          - read_scanline() -- lead with the canonical C++ binding
               explanation
               parameters
               example in C++
               language bindings: show the call signatures for C, Python, Rust
               if helpful or where it differs significantly, equivalent example in Python/C/Rust
          ...
Chapter: ImageOutput
      ...
Chapter: ImageBuf
...
[ no separate chapters just for language bindings ]

I'm not sure I have strong feelings about this yet. Just starting to think it through. But I'm very interested in hearing opinions.

As a consumer of the docs, is it more important to

• keep all the Python information together, and all the C info together, and the Rust together, and assume that readers will cross-reference with the C++ in a different chapter to find the more detailed explanations about each call?

• keep all the discussion about a particular class (e.g., ImageInput) or API operation (read_scanlines) in one place, and say there how it is accomplished in each of several languages?

[scott-wilson]

So, here's something that may throw a wrench in the documentation. Rust has a way to automatically generate documentation and also use code examples in documentation as tests. An example is here https://doc.rust-lang.org/std/string/struct.String.html (Even though this is the standard documentation, all documentation uses the same doc builder). More information can be found here https://doc.rust-lang.org/stable/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments.

I'm not sure how this plays into what you're saying, but worst case is we'll have two places for documentation in Rust (likely docs.rs for auto-generated docs, and the main oiio docs page).

[lgritz]

Yeah, I remember reading those things about Rust and I thinking it's a great idea. Rust does a lot of things right. I wish C++ had a single standard formatter, docs generator, and test system as part of the language spec.

I'll still need to document the C interface, so the basic question stands. But we should allow for the possibility that the Rust API might be separate -- either exclusively separate, or maybe have a redundant summary in the main docs.

Thanks for pointing that out.

[scott-wilson]

I think for all the languages, the nicest/best thing would probably be the last two options in my experience. I know as a user, there's been a few times when I'd need to look at the full C++ documentation, and the Python specific arguments. Having both on the same page would be amazing.

As for the Rust documentation, as long as the code is documented, then we have documentation. So, I don't know if we need to worry any more than "make sure there's documentation in the code, and preferably code examples in said documentation".

On Fri., Oct. 23, 2020, 10:59 p.m. Larry Gritz, [email protected] wrote:

Yeah, I remember reading those things about Rust and I thinking it's a great idea. Rust does a lot of things right. I wish C++ had a single standard formatter, docs generator, and test system as part of the language spec.

I'll still need to document the C interface, so the basic question stands. But we should allow for the possibility that the Rust API might be separate -- either exclusively separate, or maybe have a redundant summary in the main docs.

Thanks for pointing that out.

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/OpenImageIO/oiio/issues/2754#issuecomment-715752614, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAVFQOAEKCFUMXIUGZI4ZELSMJULXANCNFSM4S5HV25A .

[lgritz]

Closing. This was just a discussion, not an issue.