Why I can't separately write namespace's hierarchy in the header file?

Question

I write some header file. I want separately declare the namespaces hierarchy (for clarity), and and then declare functions and classes. For me it looks as a table of contents in the document. It would be very convenient for me: to see the full hierarchy of namespaces in one place. I write this:

// Namespaces hierarchy:
namespace Bushman{
    namespace CAD_Calligraphy{}
    //...
}

// Declarations of classes and functions
class Bushman::CAD_Calligraphy::Shp_ostream{
public:
    explicit Shp_ostream(std::ostream& ost);
};

But MS Visual Studio shouts on such way of creation of the header file. I should write so:

namespace Bushman{
    namespace CAD_Calligraphy{
        class Shp_istream{
        public:
            explicit Shp_istream(std::istream& ist);
        };
    }
}

Why the first variant doesn't work? Is this restriction of the C++, or IDE?

P.S. My additional question is here.

Thank you.

Answer 1

The restriction is in §9/1: "If a class-head-name contains a nested-name-specifier, the class-specifier shall refer to a class that was previously declared directly in the class or namespace to which the nested-name-specifier refers[...]". In other words, the first appearance of the class name cannot be in something like Bushman::CAD_Calligraphy::Shp_ostream.

What you can do is add forward declarations in your initial declaration of the hierarchy:

// Namespaces hierarchy:
namespace Bushman{
    namespace CAD_Calligraphy{
        class Shp_ostream;
        //...
    }
    //...
}

// Declarations of classes and functions
class Bushman::CAD_Calligraphy::Shp_ostream{
public:
    explicit Shp_ostream(std::ostream& ost);
};

Depending on how your headers are organized, this might even be better from the human point of view: your header starts with a sort of index of what is defined in it.