如何用C设计和实现抽象数据类型（封装）

衍生阅读。如何使用adt自动生成程序文档。

学习用 doxygen 生成源码文档
Doxygen在近期的版本支持了markdown语法
idea-markdown
clion中的docygen支持。

C可以用于设计和实现抽象数据类型（ADT），因为它可以限制函数和数据定义的作用域。这个技巧也被称为黑盒设计。抽象数据类型的基本想法是很简单的–模块具有功能说明和接口说明，前者说明模块所执行的任务，后者定义模块的使用。但是，模块的用户并不需要知道模块实现的任何细节，而且除了那些定义好的接口之外，用户不能以任何方式访问模块。
限制对模块的访问是通过static关键字的合理使用实现的，它可以限制对那些并非接口的函数和数据的范围。例如，考虑一个用于维护一个地址/电话号码列表的模块。模块必须提供函数，根据一个指定的名字查找地址和电话号码。但是，类别存储的方式是依赖与具体实现的，所以这个信息为模块所私有，客户并不知情。
下一个例子程序说明了这个模块的一种可能的实现方法，它定义了一个头文件，它定义了一些由客户使用的接口。程序7.6b展现了这个模块的实现。

/*
 * 用于维护一个地址列表的抽象数据类型
 */
#include "addrlist.h"
#include <stdio.h>
/*
 * 每个地址的三个部分，分别保持与三个数组的对应元素中
 */

static char name[MAX_ADDRESSES][NAME_LENGTH];
static char address[MAX_ADDRESSES][ADDR_LENGTH];
static char phone[MAX_ADDRESSES][PHONE_LENGTH];

/*
 * 这个函数在数组中查找一个名字并返回找到的位置的下标
 * 如果这个名字在数组中并不存在，函数返回-1.
 */
static int find_entry(char const *name_to_find)
{
    int entry;

    for(entry =0; entry < MAX_ADDRESSES; entry += 1)
        if(strcmp( name_to_find, name[entry]) == 0)
            return entry;
    return -1;
}
/*
 * 给定一个名字，查找并返回对应的地址
 * 如果名字没有找到，函数返回一个NULL指针，
 */
char const *lookup_address(char const *name)
{
    int entry;
    if(entry == -1)
        return NULL;
    else
        return phone[entry];
}
/*
 * 给定一个名字，查找并返回对应的电话号码。
 * 如果名字没有找到，函数返回一个NULL指针，
*/
char const *lookup_phone(char const *name){
    int entry;
    entry = find_entry(name);
    if(entry == -1)
        return NULL;
    else
        return phone[entry];
}

/*
 * 用于维护一个地址列表的抽象数据类型
 */
#include "addrlist.h"
#include <stdio.h>
/*
 * 每个地址的三个部分，分别保持与三个数组的对应元素中
 */

static char name[MAX_ADDRESSES][NAME_LENGTH];
static char address[MAX_ADDRESSES][ADDR_LENGTH];
static char phone[MAX_ADDRESSES][PHONE_LENGTH];

/*
 * 这个函数在数组中查找一个名字并返回找到的位置的下标
 * 如果这个名字在数组中并不存在，函数返回-1.
 */
static int find_entry(char const *name_to_find)
{
    int entry;

    for(entry =0; entry < MAX_ADDRESSES; entry += 1)
        if(strcmp( name_to_find, name[entry]) == 0)
            return entry;
    return -1;
}
/*
 * 给定一个名字，查找并返回对应的地址
 * 如果名字没有找到，函数返回一个NULL指针，
 */
char const *lookup_address(char const *name)
{
    int entry;
    if(entry == -1)
        return NULL;
    else
        return phone[entry];
}
/*
 * 给定一个名字，查找并返回对应的电话号码。
 * 如果名字没有找到，函数返回一个NULL指针，
*/
char const *lookup_phone(char const *name){
    int entry;
    entry = find_entry(name);
    if(entry == -1)
        return NULL;
    else
        return phone[entry];
}