Using comments as docstrings

[zdb999]

I've been playing around with the Sandstorm bindings, and often I've had problems interpreting the methods from the generated docs. I end up bouncing back and forth between the capnp spec and the generated Rust code several times when trying to understand each a relatively simple operation. It would be really helpful if the generated Rust code incorporated the documentation in the .capnp files. Would it be possible for a macro to convert the comments in .capnp files into Rust docstrings? Would it make sense to do so?

[dwrensha]

Yes, this would be possible: https://github.com/capnproto/capnproto/blob/a68afd9e78839a7cf2a83b5e49134c5161f7a2d2/c%2B%2B/src/capnp/schema.capnp#L498-L500

And yes, I think it would be a good idea.

[zdb999]

I've been playing around with this, and it appears that the sourceInfo list is always empty. (I'm calling gen.request.get_source_info()?) Do you know why this might be occurring?

[dwrensha]

What version of the capnp tool do you have installed? (What's the output of capnp --version?)

[zdb999]

It's version 0.6.1.

[dwrensha]

Ah, I think the source_info stuff was added in 0.7.

[schreter]

I also vote for supporting this. We have capnp files with extensive documentation, which isn't propagated to the generated files in Rust. Our C++ version of the code uses a special generator transforming capnp IDL files into Doxygen comments, so we have nice combined reference docs for C++ code. It would be nice to have this for pure Rust development as well.

[dwrensha]

If the schema file has comments on struct fields, where in the generated code should those comments live? Each field maps to many methods split among the Reader and Builder objects, and duplicating the comments seems wasteful. Maybe the canonical place would be for them to go on the Reader::get_*() methods?

[schreter]

Right... The C++ version we have is actually generating dummy headers with C++ structs (i.e., without accessors, plain fields, and pointers for referenced structs/lists). This is used in our Doxygen documentation generator to generate the docs and only for this.

In Rust, generated code contains top-level objects like modules for each capnp struct or enums for each capnp enum. That's indeed easy to document. Also enum members are easy to document. Struct fields are the problem.

There are several potential options how to handle struct fields:

• For each getter/setter/initer/... simply copy the documentation of the respective field and add a sentence describing what that method does with the field (or add it to the first line in braces at the end). This, of course, multiplies the documentation, which is not really good.
• Generate an additional Plain struct in the struct's module containing normal fields and add documentation there. References to other structs can be made simple references, lists and similar then via a dummy documentation List struct (Rust struct, potentially in a private module), so it's also easy to follow. For getters/setters/initers generate a small comment linking to the documentation in this Plain struct.
• Also for each Reader/Builder/Owned/... potentially add a small doc comment referring to the enclosing struct module documentation, so it's easy to navigate there.

I'd personally go for the second option (i.e., generate additional Plain struct in the struct module for documentation purposes). Then, it's self-contained. One could potentially implement some trait on this Plain struct to prevent it from being materialized and misused.

The name Plain is of course also not optimal, but Documentation fits even less. Maybe you have better ideas :-).

[dzfranklin]

What if

• single line doc comments on fields are duplicated across all methods relating to that field
• multi-line doc comments on fields get the first line duplicated and the full docs added to the module documentation of the containing struct or so on
• structs and so on are documented in the module documentation