Establish Distinction between public and private headers

[JoshuaSBrown]

A clear distinction in missing between what in parthenon should be publicly exposed. This makes it easy to break down stream code that depends on parthenon as a library as internal changes are likely to break down stream packages.

It would be nice to list the classes and functions that external programs need access to so as to hide internals and thus make parthenon more robust as a dependency.

[Yurlungur]

This is clearly important and something we need to eventually clarify and stick to. Thanks for bringing it up.

That said, I'm not sure we're ready to solidify this... It's true that we're beginning to build things downstream with parthenon, but we haven't written enough, I think, to know what should and should not be public. And also parthenon itself is still changing pretty rapidly. I think trying to keep up an API while parthenon is still in flux will be a challenge.

[AndrewGaspar]

I agree with @JoshuaSBrown. My concern with waiting is that it ossifies the exported APIs.

[AndrewGaspar]

My proposal for this is:

• Create separate include and internal directories for public and private headers, respectively.
• Move every currently existing header file to include.
• Going forward, names should be deliberately placed in either the include or internal directory
• For names that must be published but are ultimately implementation details, they should go into the parthenon::internal namespace

[Yurlungur]

That seems reasonable to me. As discussed with @nmsriram yesterday, I also think we should try to deliberately make better use of forward declarations if we can, to reduce the amount of private headers that end up "published" via a tree of includes.

[JoshuaSBrown]

Well, I will start this process by moving all headers to a public includes folder. Will probably wait until after this has been merged though. #238