documentation for several for #80

app/models/dataset.rb

@@ -1,23 +1,29 @@
-## This file contains the Dataset model, which maps the database table Datasets for the application. The Dataset title must be unique.
-##
-## Datasets contain the general metadata of a dataset. In addition, a dataset can contain:
-## 1. Primary research data, as uploaded data values from a "Dataworkbook", where the measurement information is stored in the "Datacolumn"
-## and the data values in "Sheetcell"s. The original "Dataworkbook" is stored as a "Datafile" which is referenced by the Dataset, in the "upload_spreadsheet_id" field.
-## 2. one or more asset ("Freeformat") files.
-##
-## Datasets are taggable, that is, they can be linked to entries in the Tags table. This uses the is_taggable
-## rails gem.
-##
-## Dataset provenance is managed using the ACL9 rails gem. "User"s can be given different roles in relation to a Dataset
-## and access to the Dataset is controlled via the "Role".
-##
-## Datasets can belong to one or more "Project"s
-##
-## "Paperproposal"s contain one or more Datasets. They are linked through the "DatasetPaperProposal" class.
-##
-## Highlighted methods:
-## 1. "approve_predefined_columns": after the initial upload of data a user can bulk approve columns, without reviewing each
-## column individually. The Datacolumn must be corrected described, in that it must have a datagroup and a datatype.
+# This file contains the Dataset model, which maps the database table Datasets for the application.
+# The Dataset title must be unique.
+
+# Datasets contain the general metadata of a dataset. In addition, a dataset can contain:
+# 1. Primary research data, as uploaded data values from a Dataworkbook,
+#    where the information on the column is stored in Datacolumn instances
+#    and the data values in Sheetcell instances. The original dataworkbook is stored as a Datafile
+#    which is referenced by the dataset, in the upload_spreadsheet_id field.
+# 2. one or more asset (Freeformat) files.
+#
+# Datasets are taggable, that is, they can be linked to entries in the Tags table. This uses the is_taggable
+# rails gem.
+#
+# Dataset provenance is managed using the ACL9 rails gem. Users can be given different roles in relation
+# to a dataset (see User) and access to the dataset is controlled via the Role.
+#
+# Datasets can belong to one or more Project instances. They can also set free for download within their
+# projects.
+#
+# Paperproposal instances contain one or more datasets. They are linked through
+# the DatasetPaperproposal class.
+#
+# Highlighted methods:
+# * approve_predefined_columns : after the initial upload of data a User can bulk approve columns,
+#   without reviewing each column individually. The Datacolumn must be correctly described, in
+#   that it must have a Datagroup and a Datatype.
 
 class Dataset < ActiveRecord::Base
 

app/models/dataset_paperproposal.rb

@@ -1,3 +1,12 @@
+# This file contains the DatasetPaperproposal class definition, organising the usage of Dataset instances
+# by Paperproposal instances. Paperproposals organise the access rights to data.
+
+# The class DatasetPaperproposal links Dataset instances to Paperproposal instances. It is used
+# for determining access to the primary data from the Sheetcell instances and to Freeformatfile instances.
+#
+# DatsetPaperproposals do not store access rights directly, which is done by the acl9 gem and the
+# Role class. They contain information if a Dataset is of main or side aspect for the conclusions derived
+# from analysing data according to the Paperproposal.
 class DatasetPaperproposal < ActiveRecord::Base
   belongs_to :paperproposal
   belongs_to :dataset

app/models/paperproposal.rb

@@ -1,3 +1,15 @@
+# This file contains teh Paperproposal model definition. Paperproposals are used for organizing data exchange.
+
+# Paperproposals assemble the Dataset instances (DatasetPaperproposal) )that are
+# needed for a particular purpose, in most cases
+# a scientific analysis. *Proponents* of the paperproposal are those users (User) that have submitted
+# the paperproposal.
+#
+# Proponents submit proposals to the project board (see Role) for approval as well as hints and tipps
+# and then to the owners of datasets for the permission to use the data.
+#
+# Datasets can be of main or side aspect for the proposal. Dataset owners of main aspect datasets
+# should be offered a co-authorship in the resulting paper.
 class Paperproposal < ActiveRecord::Base
 
   # acts_as_authorization_object :subject_class_name => 'Project'

doc/README_FOR_APP

@@ -1,2 +1,5 @@
-Use this README file to introduce your application and point to useful places in the API for learning more.
-Run "rake doc:app" to generate API documentation for your models, controllers, helpers, and libraries.
+Welcome to the BEFdata documentation. Here you will find hyperlinked information that
+is generated from the comments in the original files of the code using "rake doc:app"
+which again uses the markup of Rdoc.
+
+Look for example at Dataset, Paperproposal, Project, User.