#164983 by multiple contributors: document the core database schemas

1 files changed, 92 insertions, 21 deletions

diff --git a/modules/poll/poll.install b/modules/poll/poll.install
index b8128b84f..5bdcd2cab 100644
--- a/modules/poll/poll.install
+++ b/modules/poll/poll.install
@@ -22,39 +22,110 @@ function poll_uninstall() {
  */
 function poll_schema() {
   $schema['poll'] = array(
+    'description' => t('Stores poll-specific information for poll nodes.'),
     'fields' => array(
-      'nid'     => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'runtime' => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
-      'active'  => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0)
-    ),
+      'nid'     => array(
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t("The poll's {node}.nid.")
+        ),
+      'runtime' => array(
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('The number of seconds past {node}.created during which the poll is open.')
+        ),
+      'active'  => array(
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('Boolean indicating whether or not the poll is open.'),
+        ),
+      ),
     'primary key' => array('nid'),
-  );
+    );
 
   $schema['poll_choices'] = array(
+    'description' => t('Stores information about all choices for all {poll}s.'),
     'fields' => array(
-      'chid'    => array('type' => 'serial', 'unsigned' => TRUE, 'not null' => TRUE),
-      'nid'     => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'chtext'  => array('type' => 'varchar', 'length' => 128, 'not null' => TRUE, 'default' => ''),
-      'chvotes' => array('type' => 'int', 'not null' => TRUE, 'default' => 0),
-      'chorder' => array('type' => 'int', 'not null' => TRUE, 'default' => 0)
-    ),
-    'indexes' => array('nid' => array('nid')),
+      'chid'    => array(
+        'type' => 'serial',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'description' => t('Unique identifer for a poll choice.'),
+        ),
+      'nid'     => array(
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('The {node}.nid this choice belongs to.'),
+        ),
+      'chtext'  => array(
+        'type' => 'varchar',
+        'length' => 128,
+        'not null' => TRUE,
+        'default' => '',
+        'description' => t('The text for this choice.'),
+        ),
+      'chvotes' => array(
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('The total number of votes this choice has received by all users.'),
+        ),
+      'chorder' => array(
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('The sort order of this choice among all choices for the same node.'),
+        )
+      ),
+    'indexes' => array(
+      'nid' => array('nid')
+      ),
     'primary key' => array('chid'),
-  );
-
+    );
+  
   $schema['poll_votes'] = array(
+    'description' => t('Stores per-{users} votes for each {poll}.'),
     'fields' => array(
-      'nid'      => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE),
-      'uid'      => array('type' => 'int', 'unsigned' => TRUE, 'not null' => TRUE, 'default' => 0),
-      'chorder'  => array('type' => 'int', 'not null' => TRUE, 'default' => -1),
-      'hostname' => array('type' => 'varchar', 'length' => 128, 'not null' => TRUE, 'default' => '')
-    ),
+      'nid'      => array(
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'description' => t('The {poll} node this vote is for.'),
+        ),
+      'uid'      => array(
+        'type' => 'int',
+        'unsigned' => TRUE,
+        'not null' => TRUE,
+        'default' => 0,
+        'description' => t('The {users}.uid this vote is from unless the voter was anonymous.'),
+        ),
+      'chorder'  => array(
+        'type' => 'int',
+        'not null' => TRUE,
+        'default' => -1,
+        'description' => t("The {users}'s vote for this poll."),
+        ),
+      'hostname' => array(
+        'type' => 'varchar',
+        'length' => 128,
+        'not null' => TRUE,
+        'default' => '',
+        'description' => t('The IP address this vote is from unless the voter was logged in.'),
+        ),
+      ),
     'indexes' => array(
       'hostname' => array('hostname'),
       'nid'      => array('nid'),
       'uid'      => array('uid')
-    ),
-  );
+      ),
+    );
 
   return $schema;
 }