diff --git a/DESCRIPTION b/DESCRIPTION
index 3d74ee8..fa3650f 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -40,7 +40,8 @@ Imports:
     rlang,
     tibble,
     tidyr
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
+Roxygen: list(markdown = TRUE)
 Suggests:
     rmarkdown,
     knitr,
diff --git a/NAMESPACE b/NAMESPACE
index 18c0fe2..201c081 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -24,6 +24,7 @@ export(scalarNames)
 export(scalars)
 export(sources)
 export(writeResults)
+exportClasses(ModelArray)
 exportMethods(analysisNames)
 exportMethods(elementMetadata)
 exportMethods(exampleElementData)
diff --git a/R/ModelArray_Constructor.R b/R/ModelArray_Constructor.R
index f16d709..1f50a94 100644
--- a/R/ModelArray_Constructor.R
+++ b/R/ModelArray_Constructor.R
@@ -1,16 +1,46 @@
-# Exported Functions
-
-### setClass of "ModelArray" #####
-#' An S4 class to represent element-wise scalar data and statistics.
+#' ModelArray class
+#'
+#' ModelArray is an S4 class that represents element-wise scalar data and
+#' associated statistical results backed by an HDF5 file on disk.
+#'
+#' @description
+#' A ModelArray wraps one or more element-wise scalar matrices (e.g., FD, FC,
+#' log_FC for fixel data) read lazily via \pkg{DelayedArray}, along with any
+#' previously saved analysis results. The object holds references to the
+#' underlying HDF5 file and reads data on demand, making it suitable for
+#' large-scale neuroimaging datasets.
+#'
+#' @details
+#' Each scalar in the HDF5 file is stored at \code{/scalars/<name>/values}
+#' as a matrix of elements (rows) by source files (columns). Source filenames
+#' are read from HDF5 attributes or companion datasets. Analysis results, if
+#' present, live under \code{/results/<analysis_name>/results_matrix}.
+#'
+#' ModelArray objects are typically created with the \code{\link{ModelArray}}
+#' constructor function. Element-wise models are fit with
+#' \code{\link{ModelArray.lm}}, \code{\link{ModelArray.gam}}, or
+#' \code{\link{ModelArray.wrap}}.
+#'
+#' @slot sources A named list of character vectors. Each element corresponds
+#'   to a scalar and contains the source filenames (one per input file/subject).
+#' @slot scalars A named list of \linkS4class{DelayedArray} matrices.
+#'   Each matrix has elements as rows and source files as columns.
+#' @slot results A named list of analysis results. Each element is itself a
+#'   list containing at minimum \code{results_matrix} (a
+#'   \linkS4class{DelayedArray}).
+#' @slot path Character. Path(s) to the HDF5 file(s) on disk.
+#'
+#' @seealso \code{\link{ModelArray}} for the constructor,
+#'   \code{\link{ModelArray.lm}}, \code{\link{ModelArray.gam}},
+#'   \code{\link{ModelArray.wrap}} for analysis,
+#'   \code{\link{scalars}}, \code{\link{sources}}, \code{\link{results}} for
+#'   accessors.
 #'
-#' @slot sources A list of source filenames
-#' @slot scalars A list of element-wise scalar matrix
-#' @slot results A list of statistical result matrix
-#' @slot path Path to the h5 file on disk
 #' @importClassesFrom DelayedArray DelayedArray
+#' @exportClass ModelArray
+#' @aliases ModelArray-class
 ModelArray <- setClass(
   "ModelArray",
-  # contains="DelayedArray",
   slots = c(
     results = "list",
     sources = "list",
@@ -43,21 +73,48 @@ ModelArraySeed <- function(filepath, name, type = NA) {
 
 
 
-#' Load element-wise data from .h5 file as an ModelArray object
+#' Load element-wise data from an HDF5 file as a ModelArray object
+#'
+#' @description
+#' Reads scalar matrices and (optionally) saved analysis results from an HDF5
+#' file and returns a \linkS4class{ModelArray} object.
+#'
+#' @details
+#' The constructor reads each scalar listed in \code{scalar_types} from
+#' \code{/scalars/<scalar_type>/values} in the HDF5 file, wrapping them as
+#' \linkS4class{DelayedArray} objects for lazy access. Source filenames are
+#' extracted from HDF5 attributes or companion datasets.
+#'
+#' If \code{analysis_names} is non-empty, saved results are read from
+#' \code{/results/<name>/results_matrix} along with column name metadata.
+#'
+#' \strong{Debugging tip:} If you encounter
+#' \code{"Error in h(simpleError(msg, call)) : error in evaluating the
+#' argument 'seed'..."}, check that \code{scalar_types} matches the groups
+#' present in the file. Inspect with \code{rhdf5::h5ls(filepath)}.
+#'
+#' @param filepath Character. Path to an existing HDF5 (\code{.h5}) file
+#'   containing element-wise scalar data.
+#' @param scalar_types Character vector. Names of scalar groups to read from
+#'   \code{/scalars/} in the HDF5 file. Default is \code{c("FD")}. Must match
+#'   group names in the file; verify with \code{rhdf5::h5ls(filepath)}.
+#' @param analysis_names Character vector. Subfolder names under
+#'   \code{/results/} to load. Default is \code{character(0)} (no results
+#'   loaded).
+#'
+#' @return A \linkS4class{ModelArray} object.
+#'
+#' @seealso \linkS4class{ModelArray} for the class definition,
+#'   \code{\link{h5summary}} for inspecting an HDF5 file without loading,
+#'   \code{\link{scalars}}, \code{\link{sources}} for accessing loaded data.
 #'
-#' @details:
-#' Tips for debugging:
-#' if you run into this error: "Error in h(simpleError(msg, call)) :
-#' error in evaluating the argument 'seed' in selecting a method for
-#' function 'DelayedArray': HDF5. Symbol table. Can't open object."
-#' Then please check if you give correct "scalar_types" - check via
-#' rhdf5::h5ls(filename_for_h5)
+#' @examples
+#' \dontrun{
+#' ma <- ModelArray("path/to/data.h5", scalar_types = c("FD", "FC"))
+#' ma
+#' scalars(ma)
+#' }
 #'
-#' @param filepath file
-#' @param scalar_types expected scalars
-#' @param analysis_names the subfolder names for results in .h5 file. If empty
-#' (default), results are not read.
-#' @return ModelArray object
 #' @export
 #' @import methods
 #' @importFrom dplyr %>%
diff --git a/man/ModelArray.Rd b/man/ModelArray.Rd
index defb99a..96de23c 100644
--- a/man/ModelArray.Rd
+++ b/man/ModelArray.Rd
@@ -2,46 +2,97 @@
 % Please edit documentation in R/ModelArray_Constructor.R
 \name{ModelArray}
 \alias{ModelArray}
-\title{An S4 class to represent element-wise scalar data and statistics.}
+\alias{ModelArray-class}
+\title{ModelArray class}
 \usage{
 ModelArray(filepath, scalar_types = c("FD"), analysis_names = character(0))
 
 ModelArray(filepath, scalar_types = c("FD"), analysis_names = character(0))
 }
 \arguments{
-\item{filepath}{file}
+\item{filepath}{Character. Path to an existing HDF5 (\code{.h5}) file
+containing element-wise scalar data.}
 
-\item{scalar_types}{expected scalars}
+\item{scalar_types}{Character vector. Names of scalar groups to read from
+\code{/scalars/} in the HDF5 file. Default is \code{c("FD")}. Must match
+group names in the file; verify with \code{rhdf5::h5ls(filepath)}.}
 
-\item{analysis_names}{the subfolder names for results in .h5 file. If empty
-(default), results are not read.}
+\item{analysis_names}{Character vector. Subfolder names under
+\code{/results/} to load. Default is \code{character(0)} (no results
+loaded).}
 }
 \value{
-ModelArray object
+A \linkS4class{ModelArray} object.
 }
 \description{
-An S4 class to represent element-wise scalar data and statistics.
+A ModelArray wraps one or more element-wise scalar matrices (e.g., FD, FC,
+log_FC for fixel data) read lazily via \pkg{DelayedArray}, along with any
+previously saved analysis results. The object holds references to the
+underlying HDF5 file and reads data on demand, making it suitable for
+large-scale neuroimaging datasets.
 
-Load element-wise data from .h5 file as an ModelArray object
+Reads scalar matrices and (optionally) saved analysis results from an HDF5
+file and returns a \linkS4class{ModelArray} object.
 }
 \details{
-:
-Tips for debugging:
-if you run into this error: "Error in h(simpleError(msg, call)) :
-error in evaluating the argument 'seed' in selecting a method for
-function 'DelayedArray': HDF5. Symbol table. Can't open object."
-Then please check if you give correct "scalar_types" - check via
-rhdf5::h5ls(filename_for_h5)
+ModelArray is an S4 class that represents element-wise scalar data and
+associated statistical results backed by an HDF5 file on disk.
+
+Each scalar in the HDF5 file is stored at \code{/scalars/<name>/values}
+as a matrix of elements (rows) by source files (columns). Source filenames
+are read from HDF5 attributes or companion datasets. Analysis results, if
+present, live under \code{/results/<analysis_name>/results_matrix}.
+
+ModelArray objects are typically created with the \code{\link{ModelArray}}
+constructor function. Element-wise models are fit with
+\code{\link{ModelArray.lm}}, \code{\link{ModelArray.gam}}, or
+\code{\link{ModelArray.wrap}}.
+
+The constructor reads each scalar listed in \code{scalar_types} from
+\code{/scalars/<scalar_type>/values} in the HDF5 file, wrapping them as
+\linkS4class{DelayedArray} objects for lazy access. Source filenames are
+extracted from HDF5 attributes or companion datasets.
+
+If \code{analysis_names} is non-empty, saved results are read from
+\code{/results/<name>/results_matrix} along with column name metadata.
+
+\strong{Debugging tip:} If you encounter
+\code{"Error in h(simpleError(msg, call)) : error in evaluating the
+argument 'seed'..."}, check that \code{scalar_types} matches the groups
+present in the file. Inspect with \code{rhdf5::h5ls(filepath)}.
 }
 \section{Slots}{
 
 \describe{
-\item{\code{sources}}{A list of source filenames}
+\item{\code{sources}}{A named list of character vectors. Each element corresponds
+to a scalar and contains the source filenames (one per input file/subject).}
 
-\item{\code{scalars}}{A list of element-wise scalar matrix}
+\item{\code{scalars}}{A named list of \linkS4class{DelayedArray} matrices.
+Each matrix has elements as rows and source files as columns.}
 
-\item{\code{results}}{A list of statistical result matrix}
+\item{\code{results}}{A named list of analysis results. Each element is itself a
+list containing at minimum \code{results_matrix} (a
+\linkS4class{DelayedArray}).}
 
-\item{\code{path}}{Path to the h5 file on disk}
+\item{\code{path}}{Character. Path(s) to the HDF5 file(s) on disk.}
 }}
 
+\examples{
+\dontrun{
+ma <- ModelArray("path/to/data.h5", scalar_types = c("FD", "FC"))
+ma
+scalars(ma)
+}
+
+}
+\seealso{
+\code{\link{ModelArray}} for the constructor,
+\code{\link{ModelArray.lm}}, \code{\link{ModelArray.gam}},
+\code{\link{ModelArray.wrap}} for analysis,
+\code{\link{scalars}}, \code{\link{sources}}, \code{\link{results}} for
+accessors.
+
+\linkS4class{ModelArray} for the class definition,
+\code{\link{h5summary}} for inspecting an HDF5 file without loading,
+\code{\link{scalars}}, \code{\link{sources}} for accessing loaded data.
+}