从mysql源码中学习程序注释技巧

来源：互联网发布：人工智能摄影师编辑：程序博客网时间：2024/06/14 16:09

ha_example.cc：

注释1：

/* Copyright (c) 2004, 2016, Oracle and/or its affiliates. All rights reserved.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; version 2 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */

注释2：

/**
@file ha_example.cc

@brief
The ha_example engine is a stubbed storage engine for example purposes only;
it does nothing at this point. Its purpose is to provide a source
code illustration of how to begin writing new storage engines; see also
/storage/example/ha_example.h.

@details
ha_example will let you create/open/delete tables, but
nothing further (for example, indexes are not supported nor can data
be stored in the table). Use this example as a template for
implementing the same functionality in your own storage engine. You
can enable the example storage engine in your build by doing the
following during your build process:<br> ./configure
--with-example-storage-engine

Once this is done, MySQL will let you create tables with:<br>
CREATE TABLE <table name> (...) ENGINE=EXAMPLE;

The example storage engine is set up to use table locks. It
implements an example "SHARE" that is inserted into a hash by table
name. You can use this to store information of state that any
example handler object will be able to see when it is using that
table.

Please read the object definition in ha_example.h before reading the rest
of this file.

@note
When you create an EXAMPLE table, the MySQL Server creates a table .frm
(format) file in the database directory, using the table name as the file
name as is customary with MySQL. No other files are created. To get an idea
of what occurs, here is an example select that would do a scan of an entire
table:

@code
ha_example::store_lock
ha_example::external_lock
ha_example::info
ha_example::rnd_init
ha_example::extra
ENUM HA_EXTRA_CACHE        Cache record in HA_rrnd()
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::rnd_next
ha_example::extra
ENUM HA_EXTRA_NO_CACHE     End caching of records (def)
ha_example::external_lock
ha_example::extra
ENUM HA_EXTRA_RESET        Reset database to after open
@endcode

Here you see that the example storage engine has 9 rows called before
rnd_next signals that it has reached the end of its data. Also note that
the table in question was already opened; had it not been open, a call to
ha_example::open() would also have been necessary. Calls to
ha_example::extra() are hints as to what will be occuring to the request.

A Longer Example can be found called the "Skeleton Engine" which can be
found on TangentOrg. It has both an engine and a full build environment
for building a pluggable storage engine.

Happy coding!<br>
    -Brian
*/

这里分出几个层次：

（1）@file 给出本程序文件名

（2）@brief 给出本程序摘要（概括介绍本程序）

（3）@detail 主要功能和其他细节

（4）@note 需要注意的地方

（5）@code ...@endcode 给出本程序中函数框架

（6）其他

（7）程序员姓名或化名

这些都是在写程序之前完成的

注释3：

/* Interface to mysqld, to check system tables supported by SE */
static const char* example_system_database();
static bool example_is_supported_system_table(const char *db,
const char *table_name,
bool is_sql_layer_system_table);

Example_share::Example_share()
{
thr_lock_init(&lock);
}

在函数上面一行或几行给出本函数具体功能

注释4：

/**
@brief
If frm_error() is called then we will use this to determine
the file extensions that exist for the storage engine. This is also
used by the default rename_table and delete_table method in
handler.cc.

For engines that have two file name extentions (separate meta/index file
and data file), the order of elements is relevant. First element of engine
file name extentions array should be meta/index file extention. Second
element - data file extention. This order is assumed by
prepare_for_repair() when REPAIR TABLE ... USE_FRM is issued.

@see
rename_table method in handler.cc and
delete_table method in handler.cc
*/

static const char *ha_example_exts[] = {
NullS
};

可以写的更规范详细一些

注释5：

static bool example_is_supported_system_table(const char *db,
                                              const char *table_name,
                                              bool is_sql_layer_system_table)
{
st_handler_tablename *systab;

// Does this SE support "ALL" SQL layer system tables ?
if (is_sql_layer_system_table)
    return false;

// Check if this is SE layer system tables
systab= ha_example_system_tables;
while (systab && systab->db)
{
    if (systab->db == db &&
        strcmp(systab->tablename, table_name) == 0)
      return true;
    systab++;
}

return false;
}

可以对函数里面对于一些难以理解的地方做注释

注释6：

static MYSQL_SYSVAR_ENUM(
enum_var,                       // name
srv_enum_var,                   // varname
PLUGIN_VAR_RQCMDARG,            // opt
"Sample ENUM system variable.", // comment
NULL,                           // check
NULL,                           // update
0,                              // def
&enum_var_typelib);             // typelib

可以对一些难理解变量做注释

注释7：

int rnd_init(bool scan);                                      //required
int rnd_end();
int rnd_next(uchar *buf);                                     ///< required
int rnd_pos(uchar *buf, uchar *pos);                          ///< required
void position(const uchar *record);                           ///< required
int info(uint);                                               ///< required
int extra(enum ha_extra_function operation);
int external_lock(THD *thd, int lock_type);                   ///< required

可以对需要实现的函数或其他做required或其他提示

阅读全文

0 0