RE: class library header file naming and install conventions

["Jeff Hill" <johill@lanl.gov>]

> 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.

Such tools have been around for a long time. People were using them on the
VAX when I started here in 1986. I'm sure they have learned a thing or two
since then so perhaps I should look closer at doxygen. The argument for use
of doxygen type programs is that programmers are more likely to work on
their programming language source files, and so if we store the doc there
also then maybe they will keep it current. There can also be a standard,
consistent, format. The downside maybe is that every manual reads like a
reference manual, and we are less likely to have a tutorial. We are maybe
more likely to create human friendly documentation with concept structured
indexes and html tables if the html is structured by a human?

Jeff
______________________________________________________
Jeffrey O. Hill           Email        johill@lanl.gov
LANL MS H820              Voice        505 665 1831
Los Alamos NM 87545 USA   FAX          505 665 5107

Message content: TSPA

With sufficient thrust, pigs fly just fine. However, this is
not necessarily a good idea. It is hard to be sure where they
are going to land, and it could be dangerous sitting under them
as they fly overhead. -- RFC 1925


> -----Original Message-----
> From: core-talk-bounces@aps.anl.gov [mailto:core-talk-
> bounces@aps.anl.gov] On Behalf Of Andrew Johnson
> Sent: Tuesday, March 15, 2011 9:55 AM
> To: core-talk@aps.anl.gov
> Subject: Re: class library header file naming and install conventions
> 
> 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.