Adding information in API reference outside @docs macro

docs/src/api.md

@@ -7,26 +7,33 @@ Module = [Survey]
 Order = [:type, :function]
 Private = false
 ```
-
+Survey data can be loaded from a `DataFrame` into a survey design object. The package currently supports simple random sample and stratified sample designs. 
 ```@docs
 AbstractSurveyDesign
 SimpleRandomSample
 StratifiedSample
+```
+
+```@docs
 load_data
-mean(x::Symbol, design::SimpleRandomSample)
+Survey.mean(x::Symbol, design::SimpleRandomSample)
 total(x::Symbol, design::SimpleRandomSample)
 quantile
+```
+
+It is often required to estimate population parameters for sub-populations of interest. For example, you make have of heights of people, but you want the average height of male and female separately. 
+```@docs
 by
-colnames(design::AbstractSurveyDesign)
-dim(design::AbstractSurveyDesign)
-dimnames(design::AbstractSurveyDesign)
+```
+```@docs
 plot(design::AbstractSurveyDesign, x::Symbol, y::Symbol; kwargs...)
 boxplot(design::AbstractSurveyDesign, x::Symbol, y::Symbol; kwargs...)
 hist(design::AbstractSurveyDesign, var::Symbol,
 				 bins::Union{Integer, AbstractVector} = freedman_diaconis(design, var);
 				 normalization = :density,
 				 kwargs...
     			)
-freedman_diaconis
-sturges
+dim(design::AbstractSurveyDesign)
+dimnames(design::AbstractSurveyDesign)
+colnames(design::AbstractSurveyDesign)
 ```

src/SurveyDesign.jl

@@ -1,7 +1,7 @@
 """
     AbstractSurveyDesign
 
-Supertype for every survey design type: [`SimpleRandomSample`](@ref) and [`StratifiedSample`](@ref).
+Supertype for every survey design type. 
 
 !!! note
 
@@ -13,7 +13,9 @@ abstract type AbstractSurveyDesign end
 """
     SimpleRandomSample <: AbstractSurveyDesign
 
-Survey design sampled by simple random sampling.
+
+A simple random sample dataset can be loaded from a data frame into a `SimpleRandomSample` object for downstream analyses. 
+
 # Required arguments:
 data - This is the survey dataset loaded as a DataFrame in memory. 
         Note: Keeping with Julia conventions, original data object
@@ -195,7 +197,7 @@ end
 """
     StratifiedSample <: AbstractSurveyDesign
 
-Survey design sampled by stratification.
+A stratified sample dataset can be loaded from a data frame into a `StatifiedSample` object for downstream analyses. 
 
 `strata` must be specified as a Symbol name of a column in `data`.
 

src/by.jl

@@ -1,7 +1,7 @@
 """
     by(formula, by, design, function, params)
 
-Estimate the population parameters of for subpopulations of interest for a simple random sample. For example, you make have a simple random sample of heights of people, but you want the average height of male and female separately.  
+Estimate the population parameters of for subpopulations of interest for a simple random sample.  
 
 In the following example, the mean `api00` is estimated for each county. 
 ```jldoctest
@@ -42,7 +42,7 @@ end
 """
     by(formula, by, design, function)
 
-Estimate the population parameters of for subpopulations of interest for a stratified sample. For example, you make have a simple of heights of people stratified by region, but you want the average height of male and female separately.  
+Estimate the population parameters of for subpopulations of interest for a stratified sample.  
 
 In the following example, the average `api00` is estimated for each county. 
 

src/load_data.jl

@@ -4,10 +4,7 @@ asset_path(args...) = joinpath(PKG_DIR, "assets", args...)
 """
     load_data(name)
 
-Load a dataset as a `DataFrame`.
-
-All available datasets can be found in the [`assets/`](https://github.com/xKDR/Survey.jl/tree/main/assets)
-directory.
+Load a sample dataset provided in the [`assets/`](https://github.com/xKDR/Survey.jl/tree/main/assets) directory a `DataFrame`.
 
 ```jldoctest
 julia> apisrs = load_data("apisrs")