Rudimentary documentation

sakrejda / protostan

Thin protobuf interface wrapper for Stan

BSD 3-Clause "New" or "Revised" License

2 stars 1 forks source link

Rudimentary documentation #5

Closed ariddell closed 8 years ago

ariddell commented 8 years ago

What's the best way to document the proto files and the shim C++ files? It would be nice to automatically generate HTML docs for future interface writers.

sakrejda commented 8 years ago

How about this one: https://github.com/estan/protoc-gen-doc/

ariddell commented 8 years ago

That looks great.

I suppose we also need to write & generate documentation for the shim functions.

On 12/28, Krzysztof Sakrejda wrote:

How about this one: https://github.com/estan/protoc-gen-doc/

Reply to this email directly or view it on GitHub: https://github.com/sakrejda/protostan/issues/5#issuecomment-167629156

sakrejda commented 8 years ago

Yep, I think using whatever Stan uses for those is fine (doxygen?)

sakrejda commented 8 years ago

Ok, close this after we:

[x] check to make sure we can't just use doxygen comments for documenting proto files.
[x] add protoc-gen-doc generator plugin as a submodule
[x] document current messages in protoc-gen-doc format
[ ] add makefile logic to generate documentation for shim files
[ ] add makefile logic to generate documentation for proto files.

sakrejda commented 8 years ago

Had started working on this, didn't realize I didn't claim it.

sakrejda commented 8 years ago

Turns out protoc-gen-doc is not straightforward to install from source so I can't just add it as a submodule and make it go. It relies on qmake to produce the makefile and the qmake project file is hard-coded to look for system libraries. I'm not going to go through incorporating it into the makefile at this point. We can follow this format for writing the documentation comments and it'll be easier to install once protobuf-3 is the mainline system protobuf (so in a few to six months (?)).