How to force documentation when using error_chain

[andrewdavidmackenzie]

I have a library project where I would like to force documentation (and detect ommissions) using the mechanism of putting this directing in the crate root

#![deny(missing_docs)]

However, I get these errors reported, originating in error_chain.

error: missing documentation for a variant
  --> src/lib.rs:64:1
   |
64 | / error_chain! {
65 | |     types {
66 | |         Error, ErrorKind, ResultExt, Result;
67 | |     }
...  |
73 | |     }
74 | | }
   | |_^
   |
note: lint level defined here
  --> src/lib.rs:1:9
   |
1  | #![deny(missing_docs)]
   |         ^^^^^^^^^^^^
   = note: this error originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info)

I have tried adding #[allow(missing_docs)] at various places before/within the error_chain blocks, without success.

Anyone know how this can be done?

[arctic-hen7]

I know this is two years old, but I think you missed a ! in #![allow(missing_docs)], because that works for me when I put it at the top of my error definition file. Hopefully this helps someone!

[andrewdavidmackenzie]

Could you paste an example, or point me to a file/project where you have this working, as I still cannot get it to work (correctly using the directive with !) and I am not sure where to place it. Thanks.

Here is my libs.rs file for my library crate:

#![deny(missing_docs)]
#![warn(clippy::unwrap_used)]
//! Runtime library for flow execution. This will be linked with other code to produce a
//! or runner, such as `flowr` command line runner.
//!
//! It is responsible for reading a flow definition in a `Manifest` file, loading the required
//! libraries from `LibraryManifest` files and then coordinating the execution by dispatching `Jobs`
//! to be executed by `Function` `Implementations`, providing them the `Inputs` required to run and
//! gathering the `Outputs` produced and passing those `Outputs` to other connected `Functions` in
//! the network of `Functions`.
//!
#[macro_use]
extern crate error_chain;

/// `coordinator` is the module that coordinates the execution of flows submitted to it
pub mod coordinator;
/// `flowruntime` module implements the executor/server side of the runtime functions and appears
/// to user code like a library
mod flowruntime;
/// `info` offers methods to get information about this library
pub mod info;
/// `loader` is responsible for loading a flow from it's manifest and loading libraries it uses
pub mod loader;

/// `client_server` module contains a number of implementations of the communications between the
/// runtime client, debug client and the runtime server and debug server.
#[allow(unused_attributes)]
#[cfg_attr(feature = "distributed", path = "client_server/message_queue.rs")]
#[cfg_attr(not(feature = "distributed"), path = "client_server/channels.rs")]
pub mod client_server;

/// 'debug' defines structs passed between the Server and the Client regarding debug events
/// and client responses to them
#[cfg(feature = "debugger")]
pub mod debug_messages;

/// 'runtime_messages' defines messages passed between the Server and the Client during flow execution
pub mod runtime_messages;

/// Structure that defines/tracks the current runtime state
pub mod run_state;

#[cfg(feature = "debugger")]
mod debugger;

mod execution;
mod wasm;

/// 'metrics' defines a struct for tracking metrics gathered during flow execution
#[cfg(feature = "metrics")]
pub mod metrics;

/// We'll put our errors in an `errors` module, and other modules in this crate will `use errors::*;`
/// to get access to everything `error_chain!` creates.
#[doc(hidden)]
pub mod errors {
    // Create the Error, ErrorKind, ResultExt, and Result types
    error_chain! {}
}

// Specify the errors we will produce and foreign links
#![allow(missing_docs)]
error_chain! {
    types {
        Error, ErrorKind, ResultExt, Result;
    }

    foreign_links {
        Io(std::io::Error);
        Serde(serde_json::error::Error);
        Recv(std::sync::mpsc::RecvError);
        Url(url::ParseError);
        FlowStdLib(flowstdlib::errors::Error);
        FlowrCore(flowcore::errors::Error);
    }
}

which gives this compiler error:

    Finished dev [unoptimized + debuginfo] target(s) in 0.23s
   Compiling flowsamples v0.34.10 (/Users/andrew/workspace/flow/samples)
    Checking flowr v0.34.8 (/Users/andrew/workspace/flow/flowr)
error: an inner attribute is not permitted in this context
  --> flowr/src/lib/lib.rs:62:1
   |
62 | #![allow(missing_docs)]
   | ^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: inner attributes, like `#![no_std]`, annotate the item enclosing them, and are usually found at the beginning of source files. Outer attributes, like `#[test]`, annotate the item following them.

error: aborting due to previous error

I've tried other locations but cannot yet find one that works.

[arctic-hen7]

I think you probably need to have the error_chain stuff in a different file, that's the context it's talking about. I have it working here in Diana (one of my projects).

[andrewdavidmackenzie]

I see - that kinda makes sense as that directive can only be used at the root of a module I think.... Thanks for sharing.

[arctic-hen7]

My pleasure!