Expand the readme

[jontje]

Add sections for:

• Structure/class descriptions
• Troubleshooting
• Acknowledgements

[gavanderhoorn]

May I suggest we use Doxygen and/or Sphinx for that?

The code already contains quite a lot of Doxygen compatible comments, and additional material could be added there as well. Doxygen has quite good support for this.

The ROS buildfarm also automatically generates API documentation based on Doxygen (roscpp example), so that would be a plus.

[jontje]

That sounds reasonable (though I am not sure of how to set that up), thanks for the suggestion!

Also, just to clarify what I intended with the "structure/class descriptions":

• Add a simple illustration of how the important classes are related to each other.
• Add some very brief lines for each class. For example:
  • EGMSever
    Sets up, and manages an asynchoruns UDP socket (based on a Boost.Asio UDP socket)
  • EGMAbstractInterface
    Specifies the "link" between an EGMServer and an "EGM< Variant >Interface"
  • EGMBaseInterface
    Provide base functionallity (e.g. an EGMServer instance, wraps EGM messages, generating demo references)
  • EGMControllerInterface
    Extends the base for a custom controller (e.g. wait, read and write messages)
  • EGMTrajectoryInterface
    Externds the base for executing trajectories (e.g. add trajectories to a queue, perform interpolation, provide execution progress data)

This just so that one can get a quick overview, without digging into the details.

[gavanderhoorn]

re: structure/class descriptions: that's exactly what I would put in the Doxygen docs (see the roscpp example I linked earlier).

Those can then be pushed to a gh-pages branch and we'll have them hosted right here on github.

[jontje]

Ok, great :)

[jontje]

Follow-up thought:
It would probably not hurt to have the description in both the readme (short version?) and in the API documentation (more detailed version?).

Also, I will probably add some hints on how to build the library on Windows as well.

[gavanderhoorn]

My suggestion would be to avoid duplication as much as possible.

The rendered documentation would be hosted on github (so available on-line for everyone).

Additionally, users can generate it off-line on their own machines (provided they have doxygen installed).

And even without doxygen, the additional overviews/samples are readable, as it's all just plain text.

Also, I will probably add some hints on how to build the library on Windows as well.

If we get #3 fixed, building on Windows should be straightfoward: CMake supports Windows just as well as other platforms.

[traversaro]

Besides #3, a few additional fixes will be necessary to correctly compiled the library on Windows. One issue for sure is symbol visibility, but that can be easily addressed by setting CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS to TRUE (see https://blog.kitware.com/create-dlls-on-windows-without-declspec-using-new-cmake-export-all-feature/).

If the library is supposed to be distributed in binary form on Windows, some additonal work may be necessary to create a relocatable CMake package (see https://cmake.org/cmake/help/v3.12/manual/cmake-packages.7.html#creating-relocatable-packages), to make sure that the library can be used also if it installed in a location different from the build-time installation destination.

[gavanderhoorn]

@traversaro: tracking potential Windows blockers in #44.

[gavanderhoorn]

@jontje: "expand the readme" is essentially an unreachable goal :) We can always expand it further.

Would it make sense to close this issue and open new ones if/when additional updates/extensions to the readme are needed?

[jontje]

@gavanderhoorn: Yes, I fully agree, I will close this.