[1/1] cpukit/libblock Doxygen Enhancement Task #1

Cynthia Rempel cynt6007 at vandals.uidaho.edu
Fri Dec 21 05:04:25 UTC 2012


Hi,

Per Dr. Sherrill's instructions, this was submitted by Matthew as part of Google Code In, and posted to this list, as I do not have committer access.

The purpose of the patch is to enhance the quality of documentation generated by Doxygen for the following files:

cpukit/libblock/src/nvdisk-sram.c
cpukit/libblock/src/bdpart-read.c
cpukit/libblock/src/bdpart-register.c
cpukit/libblock/src/ide_part_table.c
cpukit/libblock/src/blkdev.c
cpukit/libblock/src/bdpart-mount.c
cpukit/libblock/src/bdpart-sort.c
cpukit/libblock/src/show_bdbuf.c
cpukit/libblock/src/blkdev-imfs.c
cpukit/libblock/src/blkdev-blkstats.c
cpukit/libblock/src/bdpart-create.c
cpukit/libblock/src/diskdevs-init.c
cpukit/libblock/src/bdpart-write.c
cpukit/libblock/src/blkdev-ioctl.c
cpukit/libblock/src/bdpart-dump.c
cpukit/libblock/src/flashdisk.c
cpukit/libblock/src/blkdev-print-stats.c
cpukit/libblock/src/nvdisk.c

Could someone please review this patch and commit it?
Thanks!

diff --git a/cpukit/libblock/include/rtems/bdpart.h b/cpukit/libblock/include/rtems/bdpart.h
index d1d81e7..c45e109 100644
--- a/cpukit/libblock/include/rtems/bdpart.h
+++ b/cpukit/libblock/include/rtems/bdpart.h
@@ -33,6 +33,7 @@ extern "C" {
 #endif /* __cplusplus */
 
 /**
+ * @brief Manage Partitions of a Disk Device
  * @defgroup rtems_bdpart Block Device Partition Management
  *
  * @ingroup rtems_libblock
@@ -334,6 +335,8 @@ rtems_status_code rtems_bdpart_unmount(
 );
 
 /**
+ * @brief Prints the Partition Table @a Partitions with @a Count Partitions
+ *
  * Prints the partition table @a partitions with @a count partitions to
  * standard output.
  */
diff --git a/cpukit/libblock/include/rtems/blkdev.h b/cpukit/libblock/include/rtems/blkdev.h
index f29a349..e7571dd 100644
--- a/cpukit/libblock/include/rtems/blkdev.h
+++ b/cpukit/libblock/include/rtems/blkdev.h
@@ -276,7 +276,7 @@ static inline int rtems_disk_fd_reset_device_stats(int fd)
 /** @} */
 
 /**
- * @brief Common IO control primitive.
+ * @brief Common IO Control Primitive
  *
  * Use this in all block devices to handle the common set of IO control
  * requests.
@@ -344,7 +344,7 @@ rtems_status_code rtems_blkdev_create_partition(
 );
 
 /**
- * @brief Prints the block device statistics.
+ * @brief Prints the Block Device Statistics
  */
 void rtems_blkdev_print_stats(
   const rtems_blkdev_stats *stats,
@@ -353,7 +353,7 @@ void rtems_blkdev_print_stats(
 );
 
 /**
- * @brief Block device statistics command.
+ * @brief Block Device Statistics Command
  */
 void rtems_blkstats(
   FILE *output,
diff --git a/cpukit/libblock/src/bdpart-create.c b/cpukit/libblock/src/bdpart-create.c
index 209f78f..b220daa 100644
--- a/cpukit/libblock/src/bdpart-create.c
+++ b/cpukit/libblock/src/bdpart-create.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Manage Partitions of a Disk Device
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-dump.c b/cpukit/libblock/src/bdpart-dump.c
index abd85b6..ec19166 100644
--- a/cpukit/libblock/src/bdpart-dump.c
+++ b/cpukit/libblock/src/bdpart-dump.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Prints the Partition Table @a Partitions with @a Count Partitions
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-mount.c b/cpukit/libblock/src/bdpart-mount.c
index aef15df..68e0098 100644
--- a/cpukit/libblock/src/bdpart-mount.c
+++ b/cpukit/libblock/src/bdpart-mount.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Partition Management
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-read.c b/cpukit/libblock/src/bdpart-read.c
index b14fc4c..de60095 100644
--- a/cpukit/libblock/src/bdpart-read.c
+++ b/cpukit/libblock/src/bdpart-read.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Partition Management
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-register.c b/cpukit/libblock/src/bdpart-register.c
index ebaffd1..4d1c727 100644
--- a/cpukit/libblock/src/bdpart-register.c
+++ b/cpukit/libblock/src/bdpart-register.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Partition Management
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-sort.c b/cpukit/libblock/src/bdpart-sort.c
index 1114b7a..bf7b4f9 100644
--- a/cpukit/libblock/src/bdpart-sort.c
+++ b/cpukit/libblock/src/bdpart-sort.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Partition Management
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/bdpart-write.c b/cpukit/libblock/src/bdpart-write.c
index d4523e0..24f352b 100644
--- a/cpukit/libblock/src/bdpart-write.c
+++ b/cpukit/libblock/src/bdpart-write.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Partition Management
  * @ingroup rtems_bdpart
- *
- * Block device partition management.
  */
 
 /*
diff --git a/cpukit/libblock/src/blkdev-blkstats.c b/cpukit/libblock/src/blkdev-blkstats.c
index c870fe1..b8f6d48 100644
--- a/cpukit/libblock/src/blkdev-blkstats.c
+++ b/cpukit/libblock/src/blkdev-blkstats.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Block Device Statistics Command
+ * @ingroup rtems_blkdev Block Device Management
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libblock/src/blkdev-imfs.c b/cpukit/libblock/src/blkdev-imfs.c
index 290ae78..256f90c 100644
--- a/cpukit/libblock/src/blkdev-imfs.c
+++ b/cpukit/libblock/src/blkdev-imfs.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Block Device IMFS
+ * @ingroup libblock
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libblock/src/blkdev-ioctl.c b/cpukit/libblock/src/blkdev-ioctl.c
index 54360b3..2267fb0 100644
--- a/cpukit/libblock/src/blkdev-ioctl.c
+++ b/cpukit/libblock/src/blkdev-ioctl.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Common IO Control Primitive
  * @ingroup rtems_blkdev
- *
- * Block device management.
  */
 
 /*
diff --git a/cpukit/libblock/src/blkdev-print-stats.c b/cpukit/libblock/src/blkdev-print-stats.c
index 8cebeaf..6de1fd6 100644
--- a/cpukit/libblock/src/blkdev-print-stats.c
+++ b/cpukit/libblock/src/blkdev-print-stats.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Prints the Block Device Statistics
+ * @ingroup rtems_blkdev Block Device Management
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libblock/src/blkdev.c b/cpukit/libblock/src/blkdev.c
index b926f4e..c946d33 100644
--- a/cpukit/libblock/src/blkdev.c
+++ b/cpukit/libblock/src/blkdev.c
@@ -1,9 +1,8 @@
 /**
  * @file
  *
+ * @brief Block Device Management
  * @ingroup rtems_blkdev
- *
- * Block device management.
  */
 
 /*
diff --git a/cpukit/libblock/src/diskdevs-init.c b/cpukit/libblock/src/diskdevs-init.c
index 02ef392..d594ff2 100644
--- a/cpukit/libblock/src/diskdevs-init.c
+++ b/cpukit/libblock/src/diskdevs-init.c
@@ -1,3 +1,10 @@
+/**
+ * @file
+ *
+ * @brief Block Device Disk Management Initialize
+ * @ingroup rtems_disk Block Device Disk Management
+ */
+
 /*
  * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
  *
diff --git a/cpukit/libblock/src/flashdisk.c b/cpukit/libblock/src/flashdisk.c
index a9e56c9..ccea2e6 100644
--- a/cpukit/libblock/src/flashdisk.c
+++ b/cpukit/libblock/src/flashdisk.c
@@ -1,6 +1,11 @@
-/*
- * flashdisk.c -- Flash disk block device implementation
+/**
+ * @file
  *
+ * @brief Flash Disk Block Device Implementation
+ * @ingroup libblock
+ */
+
+/*
  * Copyright (C) 2007 Chris Johns
  *
  * The license and distribution terms for this file may be
diff --git a/cpukit/libblock/src/ide_part_table.c b/cpukit/libblock/src/ide_part_table.c
index 482917f..55ac875 100644
--- a/cpukit/libblock/src/ide_part_table.c
+++ b/cpukit/libblock/src/ide_part_table.c
@@ -1,10 +1,11 @@
-/*****************************************************************************
- *
- * ide_part_table.c
- *
- * The implementation of library supporting "MS-DOS-style" partition table
- *
+/**
+ * @file
  *
+ * @brief Library supporting "MS-DOS-style" Partition Table
+ * @ingroup libblock
+ */
+
+/*
  * Copyright (C) 2002 OKTET Ltd., St.-Petersburg, Russia
  *
  * Author: Konstantin Abramenko <Konstantin.Abramenko at oktet.ru>
@@ -14,7 +15,7 @@
  *  found in the file LICENSE in this distribution or at
  *  http://www.rtems.com/license/LICENSE.
  *
- *****************************************************************************/
+ */
 
 #if HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libblock/src/nvdisk-sram.c b/cpukit/libblock/src/nvdisk-sram.c
index 61d8180..6a64a42 100644
--- a/cpukit/libblock/src/nvdisk-sram.c
+++ b/cpukit/libblock/src/nvdisk-sram.c
@@ -1,11 +1,15 @@
+/**
+ * @file
+ *
+ * @brief Provide SRAM support for the NV Disk
+ * @ingroup libblock
+ */
+
 /*
  * RTEMS Project (http://www.rtems.org/)
  *
  * Copyright 2007 Chris Johns (chrisj at rtems.org)
  */
-/**
- * Provide SRAM support for the NV Disk.
- */
 
 #if HAVE_CONFIG_H
 #include "config.h"
diff --git a/cpukit/libblock/src/nvdisk.c b/cpukit/libblock/src/nvdisk.c
index 127291d..db97179 100644
--- a/cpukit/libblock/src/nvdisk.c
+++ b/cpukit/libblock/src/nvdisk.c
@@ -1,6 +1,11 @@
-/*
- * nvdisk.c -- Non-volatile disk block device implementation
+/**
+ * @file
  *
+ * @brief Non-Volatile Disk Block Device Implementation
+ * @ingroup libblock
+ */
+
+/*
  * Copyright (C) 2007 Chris Johns
  *
  * The license and distribution terms for this file may be
diff --git a/cpukit/libblock/src/show_bdbuf.c b/cpukit/libblock/src/show_bdbuf.c
index 74ff992..9fa5f52 100644
--- a/cpukit/libblock/src/show_bdbuf.c
+++ b/cpukit/libblock/src/show_bdbuf.c
@@ -1,38 +1,28 @@
-/*===============================================================*\
-| Project: RTEMS bdbuf inspector                                  |
-+-----------------------------------------------------------------+
-| File: show_bdbuf.c
-+-----------------------------------------------------------------+
-|                    Copyright (c) 2005                           |
-|                    Embedded Brains GmbH                         |
-|                    Obere Lagerstr. 30                           |
-|                    D-82178 Puchheim                             |
-|                    Germany                                      |
-|                    rtems at embedded-brains.de                     |
-+-----------------------------------------------------------------+
-| The license and distribution terms for this file may be         |
-| found in the file LICENSE in this distribution or at            |
-|                                                                 |
-| http://www.rtems.com/license/LICENSE.                           |
-|                                                                 |
-+-----------------------------------------------------------------+
-| this file contains functions to enable the monitor              |
-| to show bdbuf information                                       |
-|                                                                 |
-|                    XXX!!! ATTETION!!! XXX!!!                    |
-|                                                                 |
-| This module inspects the bdbuf data structures,                 |
-| assuming they are static, but in fact they are used very        |
-| dynamically. Therefore the results show MAY BE INCORRECT in     |
-| some cases. And, to cure this a bit, this module may block      |
-| preemption for a rather long time and therefore it may          |
-| BREAK THE REALTIME BEHAVIOUR OF YOUR SYSTEM (when in use)       |
-+-----------------------------------------------------------------+
-|   date                      history                        ID   |
-| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
-| 26.09.06  creation                                         doe  |
-|*****************************************************************|
-\*===============================================================*/
+/**
+ * @file
+ *
+ * @brief Enable the Monitor to Show bdbuf Information
+ * @ingroup rtems_bdpart
+ *
+ * This module inspects the bdbuf data structures,
+ * assuming they are static, but in fact they are used very
+ * dynamically. Therefore the results show MAY BE INCORRECT in
+ * some cases. And, to cure this a bit, this module may block
+ * preemption for a rather long time and therefore it may
+ * BREAK THE REALTIME BEHAVIOUR OF YOUR SYSTEM (when in use)
+ */
+
+/*
+ * Copyright (c) 2005
+ * Embedded Brains GmbH
+ * Obere Lagerstr. 30
+ * D-82178 Puchheim
+ * Germany
+ * rtems at embedded-brains.de
+ * The license and distribution terms for this file may be
+ * found in the file LICENSE in this distribution or at
+ * http://www.rtems.com/license/LICENSE.
+ */
 
 #if HAVE_CONFIG_H
 #include "config.h"




More information about the devel mailing list