Error codes aren't well documented

stormmq commented 7 years ago

I'm trying to make use of ucx, and I keep bumping into several interlinked issues that make it hard:-

The list of error codes isn't well documented or explained, and they are not tied back to examples of occurrence (why, how, etc)
Most functions do not document which error codes they can return and why; I find myself having to walk through source code to do this
Error codes do not distinguish the kinds of fatality, eg:-
- Programmatically wrong and always invalid (eg passing a null pointer)
- Irrecoverable, eg this is no longer going to work
- Transient or recoverable

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.

shamisp commented 7 years ago

Adding @bbenton - he is driving documentation effort. Probably we can do better job on describing the errors.

@yosefe FYI.

stormmq commented 7 years ago

Ta

bbenton commented 7 years ago

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.

stormmq commented 7 years ago

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.

shamisp commented 7 years ago

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.

stormmq commented 7 years ago

Hmmm... I'm using a complete TexLive installation for 2017.

shamisp commented 7 years ago

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 .

stormmq commented 7 years ago

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...

openucx / ucx

Error codes aren't well documented #1573