watcher not available for import

[samuelcolvin]

System details

• OS/Platform name and version: MacOS 11.6.4
• Rust version (if building from source): rustc --version: rustc 1.61.0-nightly (285fa7ecd 2022-03-14)
• Notify version (or commit hash if building from git): 5.0.0-pre.14

I'm trying to use the examples from the docs for version 5.0.0-pre.14 (or any v5 version), but I'm getting the following error:

error[E0432]: unresolved import `notify::watcher`
  --> src/lib.rs:14:57
   |
14 | use notify::{RecommendedWatcher, RecursiveMode, Result, watcher};
   |                                                         ^^^^^^^
   |                                                         |
   |                                                         no `watcher` in the root
   |                                                         help: a similar name exists in the module (notice the capitalization): `Watcher`

Not entirely clear what I'm doing wrong here, the code is taken directly from the docs/examples.

This can be replicated with the example direct from the docs:

use notify::{RecommendedWatcher, RecursiveMode, Result, watcher};
use std::time::Duration;

fn main() -> Result<()> {
    // Automatically select the best implementation for your platform.
    // You can also access each implementation directly e.g. INotifyWatcher.
    let mut watcher = watcher(Duration::from_secs(2))?;

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch("/home/test/notify", RecursiveMode::Recursive)?;

    // This is a simple loop, but you may want to use more complex logic here,
    // for example to handle I/O.
    for event in &watcher {
        match event {
            Ok(event) => println!("changed: {:?}", event.path),
            Err(err) => println!("watch error: {:?}", err),
        };
    }

    Ok(())
}

[samuelcolvin]

on further investigation, it looks like many of the examples in the docs are incorrect or broken.

Here's a working basic example:

use std::path::Path;
use std::time::Duration;
use std::thread;
use notify::{RecommendedWatcher, RecursiveMode, Result, recommended_watcher, Watcher};

fn main() -> Result<()> {
    // Automatically select the best implementation for your platform.
    let mut watcher: RecommendedWatcher = recommended_watcher(|res| {
        match res {
           Ok(event) => println!("event: {:?}", event),
           Err(e) => println!("watch error: {:?}", e),
        }
    })?;

    // Add a path to be watched. All files and directories at that path and
    // below will be monitored for changes.
    watcher.watch(Path::new("."), RecursiveMode::Recursive)?;

    thread::sleep(Duration::from_secs(10));
    Ok(())
}

[JohnTitor]

Does "the docs" mean https://github.com/notify-rs/notify#usage? As stated at the beginning, you should refer to the docs.rs/notify if you want to get a working example.
That being said, I agree it may cause confusion like yours, and we should remove/replace it with a link to the docs/examples dir, I guess (Keeping it up-to-date while having the same on doc comments/example dirs is... bothered IMHO).

[samuelcolvin]

Thanks for the reply.

To be honest, there's a number of things that I found confusing when trying to move from 4 to 5:

• https://github.com/notify-rs/notify#usage, this is also used at https://crates.io/crates/notify/5.0.0-pre.14
• the link at the beginning of the readme "5.0.0-pre.14" is broken, I think because there's no github tag for that release
• the first example at https://docs.rs/notify/5.0.0-pre.14/notify/index.html is also broken (though less severely - Path is not imported)
• I spent some time trying to use v5.0.0-pre.7 because that's the most recent tag in github, but its docs seem to be broken

Sorry to sound negative. This package is great, I really appreciate it and all the hard work - I know how hard developing and document OS software can be.

[0xpr03]

I spent some time trying to use v5.0.0-pre.7 because that's the most recent tag in github, but its docs seem to be broken

There is a tag for 5.0.0-pre.14 we sadly dropped the v in front somewhere along the way, so it's now at the bottom.
The github releases and tag list them at the start.

Edit: Direct readme link to the tag is fixed now.

[samuelcolvin]

Thanks, sorry I missed that. At least it should make fixing the link very easy.

[0xpr03]

I actually recommend you read the docs.rs linked on crates.io and in the readme. Otherwise #395 just takes the example.