Need documentation

[jackjansen]

We need documentation, on various levels:

• The C header files need to have inline documentation. This will be picked up by the various IDE's to give access to the documentation when writing. In cwipc I think I'm using something that is concise and will be parsed by most documentation tools, but I have no idea any more where I picked it up. See https://github.com/cwi-dis/cwipc_util/blob/350d8b1b6ea3120b443d8e9c93a735d6abe15168/include/cwipc_util/api.h for example.
• It would be nice to have the API documentation also available in readable/browsable form. Doxygen at the least, but I hope there's nicer looking tools available nowadays.
• We also need a readable document that explains how to use the whole lldash. Doesn't have to be very long, and could consist mainly of links to the API documentation, and links to the cwipc Python package (for use from Python) and VR2Gather (for use from C#). I think the existing C++ test/example programs should also be linked and explained.
  • Probably the installation instructions (from a built distribution) should also go in here.
  • Probably the build instructions that are currently in the top-level README should also go in here.

Unsure who to assign this too, feel free to re-assign.

[rbouqueau]

Today's call: @rbouqueau to put playout and packager in the doxygen format.

[rbouqueau]

• Romain to add the doxygen formula as well

[rbouqueau]

@jackjansen to have a look

[jackjansen]

I'm going to ask @troeggla to have a look. (Can't assign him because he's not part of this repo).

Tom, as you are a fresh pair of eyes, could you have a look at this repo, specifically at the documentation?
You may not be able to comment on this issue, if so: please open a new issue here (you should be able to do that).

• How understandable is the README? Would you have an idea how to start using this package
  • From C/C++?
  • From Python?
  • From Unity/C#?
  • Is there enough information on deployment (i.e. how you would run and test your code)
• Are you able to find the API documentation? Is it understandable enough?

[troeggla]

The README seems reasonable enough. Instructions are clear, instructions for all operating systems and all automated through CMake. I haven't tried building it myself though. Maybe you'd want some explanation at the beginning of the README explaining what lldash is and what you might want to use it for.

Do you have the Doxygen API docs available somewhere?

Edit: Maybe a sample on how to link the library from C/C++ and/or import in Python. Unity could use some explanation on how to get going with the package and how it relates to VR2Gather

[jackjansen]

Thanks @troeggla !

• We need a preamble to the README that explains what this repo is about, and where to find more information.
• Before the Build section we probably want a Use section, which explains how to use use lldash without building it yourself (downloading the pre-built releases for the platform of your choice). Probably most of the next bullets can go into this section.
• We need to somehow create the Doxygen documentation and make it available (preferably online).
  I found https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/ which shows how to use cmake (for example in the GitHub Actions) to create all the documentation in readthedocs form.
• We need to link to the existing C++ example code from the README (or from somewhere else in the documentation)
• We need to also make those examples (preferably identical) available in Python
• Maybe we also need to make them available in C#? But I'm not sure the C# wrappers can be used outside of VR2Gather...