More detailed docs for UsingShadowDecl

[kimgr]

Summary

I couldn't make sense of the docs before, so I sent a question to cfe-dev. Richard was gracious enough to fill in the blanks:
http://lists.llvm.org/pipermail/cfe-dev/2017-April/053687.html

I've tried to transfer some of his response to the Doxygen for UsingShadowDecl. Here's to hoping I captured everything correctly.

[kimgr]

Ping!

include/clang/AST/DeclCXX.h

 };
 
 /// \brief Represents a shadow declaration introduced into a scope by a
-/// (resolved) using declaration.
+/// (resolved) using declaration, whose target is made visible for name lookup.
 ///
 /// For example,
 /// \code
 /// namespace A {
-///   void foo();
+///   void foo(int);
+///   void foo(double);
 /// }
 /// namespace B {
 ///   using A::foo; // <- a UsingDecl
-///                 // Also creates a UsingShadowDecl for A::foo() in B
+///                 // Also creates UsingShadowDecls for both A::foo(int) and
+///                 // A::foo(double) in B
 /// }
 /// \endcode
+///
+/// Derived class member declarations can hide any shadow declarations brought
+/// in by a class-scope UsingDecl;
+/// \code
+/// class Base {
+/// public:
+///   void foo();
+/// };
+/// class Derived : public Base {
+/// public:
+///   using Base::foo; // <- a UsingDecl
+///   void foo();      // Hides Base::foo and suppresses its UsingShadowDecl.
+/// };
+/// \endcode
 class UsingShadowDecl : public NamedDecl, public Redeclarable<UsingShadowDecl> {
   void anchor() override;