Re: class library header file naming and install conventions

[Andrew Johnson <anj@aps.anl.gov>]

On Monday 14 March 2011 18:11:03 Jeff Hill wrote:
>
> o The C++ namespace is pdq (class lib names must be all lower case letters)
> o The master header file's name is pdq.h
> o Each exported class named Xxxx has a header file named pdq/Xxxx.h
> o The master header file has '#include "pdq/Xxxx.h"' for each exported
> class
> o The pdq.h is installed to $(EPICS_BASE)/include/pdq.h
> o The pdq/Xxxx.h are installed to $(EPICS_BASE)/include/pdq/Xxxx.h

Actually those should be $(INSTALL_LOCATION)/include/... since we do support 
installation outside of the Base tree if so configured.

> o The build system appears to implement this type of install now if, in the
> build area, one has something like src/pdq/lib/pdq which contains the
> header files (where they are installed from). Is that what we want? That
> (redundant pdq in the path) could be initially somewhat confusing to the
> uninitiated, and I don't see any reason to place the header files in a
> subdirectory other than to avoid changing the build system?

Using the new build layout in lp:~mdavidsaver/epics-base/reorg-src all the 
source and header files for the module would be in src/<something>/pdq with a 
master Makefile in src/<something> that pulls in a Makefile fragment from 
src/<something>/pdq thus the pdq in the path is not redundant.  Note that 
<something> can have multiple path components.

> o The c/c++ files are named src/pdq/lib/Xxxx.cpp

Like Ralph I don't see the purpose of the 'lib' part and it would actually 
break the new build layout.

> o The documentation master goes in src/pdq/doc/pdq.html
> o Maybe the class interface documentation goes in src/pdq/doc/pdq/Xxxx.html
> (same concerns about redundant pdq in the path)

The documentation master should be with the source code in src/<something>/pdq 
from where (if it's included in the HTMLS variable) the current build system 
can install it into $(INSTALL_LOCATION)/html or I believe into a sub-directory 
named in the HTMLS_DIR variable, or (if it's included in the DOCS variable) 
into the $(INSTALL_LOCATION)/doc directory.

As Ralph said, documentation should be installed (see the INSTALL_LOCATION 
point above).  I would encourage considering the use of a standard tool like 
doxygen, I think once you start writing in-line documentation it should make 
future maintenance easier, although I've rarely used it myself because 
introducing it after-the-fact is hard.

- Andrew
-- 
An error is only a mistake if you don't learn from it.
When you learn something from it, it becomes a lesson.