Library Documentation
The documentation for an IPW library consists of a description file (like those above), the man pages for the function categories, and the man pages for the functions themselves.
A library's description file has two sections:
The contents of the first section are stored in a file called
"Description.html"
in the library's source directory. The
second section is generated automatically from the Makefiles within
the library's source directory.
Man pages
The man pages for each category and its functions are stored in a
subdirectory called "Man"
located in the category's
source directory. The source file for the category's man page is located
in the subdirectory "Man/Category"
. This man page
typically describes the header file associated with the category.
The source file for each function's man page resides in a separate
subdirectory named after the function. For example, the source file
for the function "foo"
's man page would be located in the
subdirectory "Man/foo"
.
Makefiles
There are three levels of Makefiles within a library's source directory:
The Makefile format for the top two levels is the same; they simply list the categories in the library, and the functions in each category.
--- library Makefile --- LIB := name DESCRIPTION := ... DIRS := cat1 cat2 ... include $(IPW)/make/library --- category Makefile --- CATEGORY := name DESCRIPTION := ... FUNCS := func1 func2 ... include $(IPW)/make/funcCategory
The categories and functions appear in the library's description file
is the order specified. Each function has its own source file with
the extension ".c"
. In the example above, the source files
would be "func1.c"
, "func2.c"
, etc. Note that
the extensions are not specified with the FUNCS macro.
If a category has additional private functions that are called only by the
category's public functions and not from outside the category, then
the source files for these private functions are specified using the
optional PRIVATE_SRCS
macro:
FUNCS := ... PRIVATE_SRCS := _init.c _globals.c _newItem.c include $(IPW)/make/funcCategory
The Makefiles for the man pages for the category and its functions have the same format, differing only in the include file that's referenced:
NAME := foo DESCRIPTION := blah blah blah include $(IPW)/make/funcCatManpg or include $(IPW)/make/funcManpage