From 0a304e65065b078d42055eb960a394934b20780b Mon Sep 17 00:00:00 2001
From: Oskar Laverny <oskar.laverny@univ-amu.fr>
Date: Sat, 8 Jun 2024 17:46:22 +0200
Subject: [PATCH] [docs] Rudimentary documentation (#5)

---
 docs/src/index.md |  7 ++++++-
 src/Strata.jl     | 11 +++++++++++
 src/Surv.jl       | 11 +++++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 67baa68..22267a7 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -4,7 +4,12 @@ CurrentModule = SurvivalBase
 
 # SurvivalBase
 
-Documentation for [SurvivalBase](https://github.com/JuliaSurv/SurvivalBase.jl).
+The [`SurvivalBase.jl`](https://github.com/JuliaSurv/SurvivalBase.jl) package is intended to hold internals and shared infrastructure for several other front-facing packages in the [JuliaSurv](https://github.com/JuliaSurv) organization, while having the minimal set of dependencies. Please do not use it directly and instead used other front-facing packages and interfaces from the organization.
+
+Right now, the main infrastructure consists of special functions `Surv` and `Strata` used in [`StatsModels.jl`](https://juliastats.org/StatsModels.jl/stable/api/)'s `@formula`s to be able to express as formulas strandard survival models. 
+
+The current implementation only provides bindings for right censored survivals times (with `Surv(T,Δ)`, left-hand-side of formulas) and *stratified* estimators (with `Strata(x)`, right-hand-side of formulas), but extensions to more complex survival times (e.g. truncation and/or censoring from right and/or left) is planned (note: it would be straightforward and non-breaking). 
+
 
 ```@index
 ```
diff --git a/src/Strata.jl b/src/Strata.jl
index b57bd33..730a87f 100644
--- a/src/Strata.jl
+++ b/src/Strata.jl
@@ -1,3 +1,14 @@
+"""
+    Strata(x::Symbol)
+
+Create a `StrataTerm` object that holds a variable in the construction of a formula to stratify an estimator. 
+
+The behavior of the stratification depends on the fitted estimator: is is usally used on the right hand side of formulas from [`StatsModels.jl`](https://github.com/JuliaStats/StatsModels.jl) as
+
+    @formula(Surv(time,status) ~ Strata(covariate1) + covariate 2)
+
+It then has a behavior that unufortunately heavily depends on the estimator, e.g. stratification of a log-rank-type test. 
+"""
 Strata(x) = x
 struct StrataTerm{X} <: AbstractTerm
     Covariable::X
diff --git a/src/Surv.jl b/src/Surv.jl
index 1170fea..8f97346 100644
--- a/src/Surv.jl
+++ b/src/Surv.jl
@@ -1,3 +1,14 @@
+"""
+    Surv(T::Symbol, Δ::Symbol)
+
+Create a `SurvTerm` object that holds a tuple of variables `(T,Δ)` in the construction of a formula, usually on the left-hand-side, representing a right-censored output time `T` with its status indicatrix `Δ`: Δ being true means that the time was indeed observed, while false means censoring. 
+
+This information, usually on the left hand side a formula, has then a behavior that may depend on the estimator. It allows to use formulas from [`StatsModels.jl`](https://github.com/JuliaStats/StatsModels.jl) as follow: 
+
+    @formula(Surv(time,status) ~ covariate1 + covariate 2)
+
+This usage is common in, e.g., cox models. However, note that the *meaning* of the formula heavily depends on the model : for hazard regession and maximum likelyhood estimation, this does not mean the same thing. 
+"""
 Surv(T::Float64, Δ::Bool) = (T, Δ)
 struct SurvTerm{X, Y} <: AbstractTerm
     T::X