The pipe (|) in @return works to specify multiple return types from a normal method, but only the first type is seen by NetBeans in the equivalent @method. Since the hover help for @method and @property-read doesn't show, you can test that these work by using auto-complete on the returned value.

    /**
     * @method Foo|Bar foo()
     */
    class Foo
    {
        /**
         * @return Foo|Bar
         */
        public function foobar() {}
    }

    $f = new Foo;
    $f->foobar()->[CTRL+SPACE] auto-complete shows members for both [CORRECT]
    $f->foo()->[CTRL+SPACE] auto-complete shows members for Foo only [WRONG]