[petsc-dev] Stricter header includes

[Barry Smith]

On Feb 12, 2013, at 4:41 PM, Jed Brown <jedbrown at mcs.anl.gov> wrote:

> 
> On Tue, Feb 12, 2013 at 4:37 PM, Matthew Knepley <knepley at gmail.com> wrote:
> On Tue, Feb 12, 2013 at 5:34 PM, Barry Smith <bsmith at mcs.anl.gov> wrote:
> 
>    Certain PETSc "functions" are documented as being "Developer" level. Does this mean they will be in a "developer" API as opposed to the "user" API (for example in xxximpl.h instead of petscxxx.h)?  Or will there not be a "developer" API at all and xxximpl.h merely provides access to the direct data structure.
> 
> I thought Developer meant "we are still figuring this out", or "you can really hurt yourself here", not "this is secret".
> 
> That was my impression too. I thought the actual internal stuff did not have a generated man page.

   So we don't need documentation for our own stuff? Consider the manual page for PetscHeaderCreate(), that is truly a "developer" operation which has a manual page and is in petscimpl.h (where it should be, it needn't be public). Maybe we need both a "Developer" level and a "Experimental"/"Dangerous"/"New" level?

   Barry

> 
> It's possible to be a bit more strict about this by enabling visibility. When configured using --with-visibility, internal functions become "invisible" outside the shared library (even those that aren't file-local). To make that more precise and explicit, we could use PETSC_INTERNAL instead of PETSC_EXTERN for those functions.