rename parrot.h to internals.h or private.h or equivalent

[pmichaud]

Several lines at the beginning of parrot.h read:

/* Only parrot core files should include this file.
   Extensions should include <parrot/extend.h>.
   Programs embedding parrot should include <parrot/embed.h>.
*/

A far more effective approach would be to rename "parrot.h" to "internals.h" or "private.h" or something that makes it much more obvious that the contents are meant for internal use only. People looking to Parrot source code for examples of how to write PMCs, dynpmcs or dynops are unlikely to read the contents of parrot.h and see the warning.

Pm

[jkeenan]

Will this require a deprecation cycle?

[whiteknight]

That comment in parrot.h is misleading, and I've just pushed an update for it. parrot.h is often required in extending situations, because extend.h is woefully incomplete. We haven't taken any effort to make a separate extending API beyond the individual APIs of our various subsystems.

As for renaming the file, I don't think it brings us any benefit considering the amount of work involved. -1 from me, although I am happy to update any documentation that could be more clear.

Jim: This definitely would require a deprecation cycle.