improve docstrings for fit measures

Author: Alexey Stukalov

src/frontend/fit/fitmeasures/AIC.jl

@@ -1,6 +1,6 @@
 """
-    AIC(sem_fit::SemFit)
+    AIC(fit::SemFit)
 
-Return the akaike information criterion.
+Calculate the *AIC* ([*Akaike information criterion*](https://en.wikipedia.org/wiki/Akaike_information_criterion)).
 """
-AIC(sem_fit::SemFit) = minus2ll(sem_fit) + 2nparams(sem_fit)
+AIC(fit::SemFit) = minus2ll(fit) + 2nparams(fit)

src/frontend/fit/fitmeasures/BIC.jl

@@ -1,6 +1,6 @@
 """
-    BIC(sem_fit::SemFit)
+    BIC(fit::SemFit)
 
-Return the bayesian information criterion.
+Calculate the *BIC* ([*Bayesian information criterion*](https://en.wikipedia.org/wiki/Bayesian_information_criterion)).
 """
-BIC(sem_fit::SemFit) = minus2ll(sem_fit) + log(nsamples(sem_fit)) * nparams(sem_fit)
+BIC(fit::SemFit) = minus2ll(fit) + log(nsamples(fit)) * nparams(fit)

src/frontend/fit/fitmeasures/RMSEA.jl

@@ -1,13 +1,19 @@
 """
     RMSEA(fit::SemFit)
 
-Return the RMSEA.
+Calculate the RMSEA ([*Root Mean Squared Error of Approximation*](https://meth.psychopen.eu/index.php/meth/article/download/2333/2333.html?inline=1#sec1)):
+``
+\\mathrm{RMSEA} = \\sqrt{\\frac{\\chi^2 - N_{\\mathrm{df}}}{N_{\\mathrm{obs}} * N_{\\mathrm{df}}}},
+``
+where `χ²` is the chi-squared statistic, `df` is the degrees of freedom, and `N_obs` is the number of observations
+for the SEM model.
 """
 function RMSEA end
 
 RMSEA(fit::SemFit) = RMSEA(fit, fit.model)
 
-RMSEA(fit::SemFit, model::AbstractSemSingle) = RMSEA(dof(fit), χ²(fit), nsamples(fit))
+RMSEA(fit::SemFit, model::AbstractSemSingle) =
+    RMSEA(dof(fit), χ²(fit), nsamples(fit))
 
 RMSEA(fit::SemFit, model::SemEnsemble) =
     sqrt(length(model.sems)) * RMSEA(dof(fit), χ²(fit), nsamples(fit))

src/frontend/fit/fitmeasures/chi2.jl

@@ -1,7 +1,11 @@
 """
     χ²(fit::SemFit)
 
-Return the χ² value.
+Calculate the *χ²* (*chi-square*) value for the `fit`.
+
+The *χ²* is a test statistic for the SEM goodness-of-fit.
+It compares the *implied* covariance matrix of the SEM model
+with the *observed* covariance matrix.
 """
 χ²(fit::SemFit) = χ²(fit, fit.model)
 

src/frontend/fit/fitmeasures/dof.jl

@@ -1,12 +1,18 @@
 """
-    dof(sem_fit::SemFit)
+    dof(fit::SemFit)
     dof(model::AbstractSem)
 
-Return the degrees of freedom.
+Get the *degrees of freedom* for the SEM model.
+
+The degrees of freedom for the SEM model with *N* observed variables
+is the difference between the number of parameters
+required to define the *N×N* covariance matrix (*½N(N+1)*)
+(plus *N* parameters for the observed means vector, if present),
+and the number of model parameters, [`nparams(model)`](@ref nparams).
 """
 function dof end
 
-dof(sem_fit::SemFit) = dof(sem_fit.model)
+dof(fit::SemFit) = dof(fit.model)
 
 dof(model::AbstractSem) = n_dp(model) - nparams(model)
 

src/frontend/fit/fitmeasures/minus2ll.jl

@@ -1,7 +1,7 @@
 """
     minus2ll(sem_fit::SemFit)
 
-Return the negative 2* log likelihood.
+Calculate the *-2log(likelihood(fit))*.
 """
 function minus2ll end
 

src/frontend/fit/fitmeasures/p.jl

@@ -1,6 +1,6 @@
 """
-    p(sem_fit::SemFit)
+    p_value(fit::SemFit)
 
-Return the p value computed from the χ² test statistic.
+Calculate the *p*-value for the *χ²* test statistic.
 """
-p_value(sem_fit::SemFit) = ccdf(Chisq(dof(sem_fit)), χ²(sem_fit))
+p_value(fit::SemFit) = ccdf(Chisq(dof(fit)), χ²(fit))