diff --git a/src/dataset.jl b/src/dataset.jl
index 2d69157..ca0579b 100644
--- a/src/dataset.jl
+++ b/src/dataset.jl
@@ -219,6 +219,13 @@ function varbyattrib(ds::Union{AbstractDataset,AbstractVariable}; kwargs...)
     return varlist
 end
 
+"""
+    var = getindex(ds::Union{AbstractDataset,AbstractVariable},cfname::CFStdName)
+
+Return the NetCDF variable `var` with the standard name `cfname` from a
+dataset. If the first argument is a variable, then the search is limited to
+all variables with the same dimension names.
+"""
 function Base.getindex(ds::Union{AbstractDataset,AbstractVariable},n::CFStdName)
     ncvars = varbyattrib(ds, standard_name = String(n.name))
     if length(ncvars) == 1
@@ -228,7 +235,27 @@ function Base.getindex(ds::Union{AbstractDataset,AbstractVariable},n::CFStdName)
     end
 end
 
+"""
+    names = keys(g::Groups)
+
+Return the names of all subgroubs of the group `g`.
+"""
 Base.keys(groups::Groups) = groupnames(groups.ds)
+
+"""
+    group = getindex(g::Groups,groupname::AbstractString)
+
+Return the NetCDF `group` with the name `groupname` from the parent
+group `g`.
+
+For example:
+
+```julia
+ds = NCDataset("results.nc", "r");
+forecast_group = ds.group["forecast"]
+forecast_temp = forecast_group["temperature"]
+```
+"""
 Base.getindex(groups::Groups,name) = group(groups.ds,name)
 
 
diff --git a/src/dimension.jl b/src/dimension.jl
index 88b878b..bb23f43 100644
--- a/src/dimension.jl
+++ b/src/dimension.jl
@@ -85,13 +85,47 @@ function show_dim(io::IO, d)
     end
 end
 
+"""
+    keys(d::Dimensions)
+
+Return a list of all dimension names in NCDataset `ds`.
 
+# Examples
 
+```julia
+ds = NCDataset("results.nc", "r");
+dimnames = keys(ds.dim)
+```
+"""
 Base.keys(dims::Dimensions) = dimnames(dims.ds)
+
+
 Base.getindex(dims::Dimensions,name) = dim(dims.ds,name)
+
+
+"""
+    setindex!(d::Dimensions,len,name::AbstractString)
+
+Defines the dimension called `name` to the length `len`, for example:
+
+```julia
+ds = NCDataset("file.nc","c")
+ds.dim["longitude"] = 100
+```
+
+If `len` is the special value `Inf`, then the dimension is considered as
+`unlimited`, i.e. it will grow as data is added to the NetCDF file.
+"""
 Base.setindex!(dims::Dimensions,data,name) = defDim(dims.ds,name,data)
+
+
 Base.show(io::IO,dims::Dimensions) = show_dim(io,dims)
 
+"""
+    unlimited(d::Dimensions)
+
+Return the names of all unlimited dimensions.
+"""
 unlimited(dims::Dimensions) = unlimited(dims.ds)
 
 
diff --git a/src/select.jl b/src/select.jl
index 896cdd5..6cbf3ab 100644
--- a/src/select.jl
+++ b/src/select.jl
@@ -184,9 +184,10 @@ if we have a time series of temperature and salinity, the temperature values
 can also be selected based on salinity:
 
 ```julia
-# create a sample time series
 using NCDatasets, Dates
+using CommonDataModel: @select
 fname = "sample_series.nc"
+# create a sample time series
 time = DateTime(2000,1,1):Day(1):DateTime(2009,12,31)
 salinity = randn(length(time)) .+ 35
 temperature = randn(length(time))
@@ -202,10 +203,11 @@ ds = NCDataset(fname)
 # load all temperature data from January where the salinity is larger than 35.
 v = @select(ds["temperature"],Dates.month(time) == 1 && salinity >= 35)
 
-# this is equivalent to
+# this is equivalent to:
 v2 = ds["temperature"][findall(Dates.month.(time) .== 1 .&& salinity .>= 35)]
 
-@test v == v2
+v == v2
+# returns true
 close(ds)
 ```