From 2cfd6b777061f0ba51e0e8ea478fdc2e7c93cde4 Mon Sep 17 00:00:00 2001
From: ayushpatnaikgit <ayushpatnaik@gmail.com>
Date: Thu, 1 Dec 2022 21:11:04 +0530
Subject: [PATCH] Adding information in API reference outside @docs macro

---
 docs/src/api.md     | 21 ++++++++++++++-------
 src/SurveyDesign.jl |  8 +++++---
 src/by.jl           |  4 ++--
 src/load_data.jl    |  5 +----
 4 files changed, 22 insertions(+), 16 deletions(-)

diff --git a/docs/src/api.md b/docs/src/api.md
index 53028358..acbb5da0 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -7,19 +7,25 @@ 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,
@@ -27,6 +33,7 @@ hist(design::AbstractSurveyDesign, var::Symbol,
 				 normalization = :density,
 				 kwargs...
     			)
-freedman_diaconis
-sturges
+dim(design::AbstractSurveyDesign)
+dimnames(design::AbstractSurveyDesign)
+colnames(design::AbstractSurveyDesign)
 ```
diff --git a/src/SurveyDesign.jl b/src/SurveyDesign.jl
index 622a69f2..6075c22d 100644
--- a/src/SurveyDesign.jl
+++ b/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`.
 
diff --git a/src/by.jl b/src/by.jl
index cc4585ef..4e2ac360 100644
--- a/src/by.jl
+++ b/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. 
 
diff --git a/src/load_data.jl b/src/load_data.jl
index bfae08d4..41f727ee 100644
--- a/src/load_data.jl
+++ b/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")