Exit codes

[Kapeli]

Is there any way to get Yard to have a different exit code for fatal errors? For example, if an error occurred and no docs were generated, yard should exit with code 1. As far as I can tell, Yard always exists with code 0, which makes it hard to determine what happened

[lsegal]

In the case where an exception occurs, Ruby should handle that scenario and exit with nonzero status.

In the case where "no docs were generated"-- it's hard to even know if that's an "error" or not.

Are you asking about scenarios where YARD explicitly reports error messages about generating HTML files?

[Kapeli]

I need to make a difference between fatal errors and other errors.

For example, between these two:

Fatal error (no docs generated):

~/Desktop/gem/aws-sdk-1.36.1 » yard doc
[error]: The file `doc-src/api_docs_plugin.rb' could not be loaded:
cannot load such file -- doc-src/api_docs_plugin.rb

Error (some docs generated):

~/Desktop/gem/ox-2.1.1 » yard doc
[warn]: Unknown tag @column in file `lib/ox/sax.rb` near line 52
[error]: Unhandled exception in YARD::Handlers::C::ClassHandler:
[error]:   in `ext/ox/sax_as.c`:245:

    245: ox_sax_value_class = rb_define_class_under(sax_module, "Value", rb_cObject);

Files:          15
Modules:         2 (    0 undocumented)
Classes:        15 (    2 undocumented)
Constants:       1 (    0 undocumented)
Methods:        30 (    1 undocumented)
 93.75% documented

On both occasions the exit code is 0.

Is it safe to assume that if a fatal error occurs and yard does not generate anything, there won't be a "doc" folder at all?

[lsegal]

Well-- technically you cannot assume that, no. Technically speaking, a plugin, or YARD itself, could fail at HTML generation time, possibly mid-way through generating files inside of doc/. Anything is possible, really.

The errors you've described, though, would have the behavior of not making to to generating the doc/ directory, so that's a behavior you could rely on for now.

I do agree that the first case should generate a nonzero exit code. The latter case should not necessarily be a nonzero exit-- I suppose it's debatable whether we should treat any parse error as a complete YARD failure, though in that case YARD is still able to generate documentation, so I'm not sure it's a "fatal" error.

[Kapeli]

Technically speaking, a plugin, or YARD itself, could fail at HTML generation time, possibly mid-way through generating files inside of doc/.

Wouldn't the exit code be nonzero in this case?

[Kapeli]

Also, one idea could be to change the [error]: in ext/ox/sax_as.c:245: message to [parser error]: in ext/ox/sax_as.c:245:.

This way I could just check for [error] and assume something bad happened.

[lsegal]

Wouldn't the exit code be nonzero in this case?

Yes-- in the ideal implementation, an exception during HTML generation should cause nonzero exit. I was responding to your point about fatal errors implying that nothing is generated. That's not true, unfortunately. It's possible for fatal errors to occur after doc/ is created and partially filled.

Also, one idea could be to change the [error]: in ext/ox/sax_as.c:245: message to [parser error]: in ext/ox/sax_as.c:245:.

We use the Logger interface, so we only have specific methods. We could, and probably should, use "fatal" for the load error case, though. but I'm not sure fatal would be appropriate for the other cases (like exceptions during parsing or HTML generation), as they are technically not "fatal"-- YARD is able to recover.

[lsegal]

FWIW you should be able to check for "[error]" today. If you see any error lines, that means YARD did something wrong. Things that YARD doesn't recognize in code turn into warnings, not errors.

[Kapeli]

FWIW you should be able to check for "[error]" today. If you see any error lines, that means YARD did something wrong. Things that YARD doesn't recognize in code turn into warnings, not errors.

I used to do this, but it seems that the ox gem has an error (the one I listed above), but still the docs that are generated are acceptable.

I pretty much need to decide between "the docs are ok and should be displayed to the user" or "generated docs are of no use and I need to show the error to the user instead"

[Kapeli]

Oh and yes, I understand that my dilemma can only be solved by guessing, there's no way Yard could know if the docs are "ok".

[lsegal]

Technically speaking, the exception you listed looks like either a bug in YARD or some unrecognized use that we should support. In other words, YARD is not generating "correct" docs for that SAX::Value class (or whatever it is actually inside of). If you want to strictly decide if docs are "ok", then that error should imply that docs are not 100% okay. There is at least one issue in your docs due to that error.

[Kapeli]

Thanks for the clarifications and prompt replies!

[lsegal]

@Kapeli I'm curious what yard --backtrace gives you inside of ox? That error stack trace would be helpful, as it looks like a bug. Perhaps open a new issue?

[Kapeli]

Done: #753