First example:

I have some main class, and some subclasses, I have static method to return instance

    class dad{
        public function __construct($arg){
        }

        /**
        * @return self
        */
        public static function get($arg){
            return new static($arg);
        }
    }

    class son exteneds dad{
        public function __construct($arg){
        }

        public function sonFunc(){
            
        }
    }

    class daughter extends dad{
        public function __construct($arg){
        }

        public function daughterFunc(){
            
        }
    }

Now, I want make Netbeans IDE know, that son::get() return son, daughter::get() returns daughter  to correct codecompletion

Other example is chaining:

    class a{
        /**
        * @return self
        */
        public function x(){
            //return $this, it's not always a, it may be subclass
        }   
    }