Open stormmq opened 7 years ago
Adding @bbenton - he is driving documentation effort. Probably we can do better job on describing the errors.
@yosefe FYI.
Ta
This is certainly an area where we can improve the documentation. There are other areas as well. We will be working in the next few months to improve the documentation for issues such as this.
Ta. As an aside, @bbenton, I found generating the PDF / PS documentation rather tough going, as it prompts a lot. (This is almost certainly down to the use of LaTeX; good as it is theoretically, it's just too hard to write and maintain without a lot of effort). However, I had to do it, as I found some of the inline doxygen syntax for tables just too difficult to read unformatted in the underlying header files, and the PDF was easier to work with.
If you have doxygen + latex installed make docs
generates the PDF. It not supposed to prompt at all. Most likely this is a sign that some latex packages are missing. I think by default it also generates HTML, which is very easy to read.
Hmmm... I'm using a complete TexLive installation for 2017.
I have the following ports installed (OSX)
texlive-latex @37361_0+doc
texlive-latex-extra @37398_0+doc
texlive-latex-recommended @37384_0+doc
On Wed, Jun 7, 2017 at 9:56 AM, stormmq notifications@github.com wrote:
Hmmm... I'm using a complete TexLive installation for 2017.
— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/openucx/ucx/issues/1573#issuecomment-306820921, or mute the thread https://github.com/notifications/unsubscribe-auth/ACIe2OtgSXjVvDg6YTNV_iwdFMp4SMayks5sBroWgaJpZM4NxT0b .
My bad - I've installed mactex
via brew cask install mactex
, and added the path /usr/local/texlive/2017/bin/x86_64-darwin
to the front of my path. LaTeX is notorious for being a pain to get a consistent install for...
I'm trying to make use of ucx, and I keep bumping into several interlinked issues that make it hard:-
On the last point, there will always be slight differences in view (one man's meat is another man's poison, and all that), but additional indicators would be very useful.
It'd probably not helped by the 'classic' C design pattern of just using one enum for all error codes for all functions. Error code enums (or something equivalent) should be scoped to a range solely possible for that function. Sure, it's more work, but doing things well always is. This sort of approach makes the API far more self documenting.