Merge pull request #11 from gaelforget/docs

add second set of docstrings + fix previous commit bug

Author: gaelforget

src/gcmfaces_IO.jl

@@ -1,7 +1,12 @@
 
 ## read_bin function with full list of argument
 
-function read_bin(fil::String,kt,kk,prec::DataType);
+"""
+    read_bin(fil::String,kt,kk,prec::DataType)
+
+Read model output from binary file and convert to gcmfaces structure.
+"""
+function read_bin(fil::String,kt,kk,prec::DataType)
 
   if ~isempty(kt);
     error("non-empty kt option not implemented yet");
@@ -12,7 +17,7 @@ function read_bin(fil::String,kt,kk,prec::DataType);
   end;
 
   (n1,n2)=MeshArrays.ioSize;
-  
+
   if prec==Float64;
     reclen=8;
   else;
@@ -34,12 +39,22 @@ end
 
 ## read_bin function with reduced list of argument
 
-function read_bin(fil::String,prec::DataType);
-  read_bin(fil,[],[],prec);
+"""
+    read_bin(fil,[],[],prec)
+
+Read model output from binary file and convert to gcmfaces structure.
+"""
+function read_bin(fil::String,prec::DataType)
+  read_bin(fil,[],[],prec)
 end
 
 ## read_bin function with reduced list of argument
 
-function read_bin(fil::String);
-  read_bin(fil,[],[],Float32);
+"""
+    read_bin(fil::String)
+
+Read model output from binary file and convert to gcmfaces structure.
+"""
+function read_bin(fil::String)
+  read_bin(fil,[],[],Float32)
 end

src/gcmfaces_calc.jl

@@ -1,11 +1,21 @@
 
 ## gradient methods
 
+"""
+    gradient(inFLD::gcmfaces)
+
+Compute spatial derivatives.
+"""
 function gradient(inFLD::gcmfaces)
 (dFLDdx, dFLDdy)=gradient(inFLD,true)
 return dFLDdx, dFLDdy
 end
 
+"""
+    gradient(inFLD::gcmfaces,doDIV::Bool)
+
+Compute spatial derivatives with or without dividing by grid scale.
+"""
 function gradient(inFLD::gcmfaces,doDIV::Bool)
 
 exFLD=exchange(inFLD,1)
@@ -29,6 +39,11 @@ end
 return dFLDdx, dFLDdy
 end
 
+"""
+    gradient(inFLD::gcmfaces,iDXC::gcmfaces,iDYC::gcmfaces)
+
+Compute spatial derivatives and multiply by inverse grid scale.
+"""
 function gradient(inFLD::gcmfaces,iDXC::gcmfaces,iDYC::gcmfaces)
 
 exFLD=exchange(inFLD,1)
@@ -49,11 +64,21 @@ end
 
 ## mask methods
 
+"""
+    mask(fld::gcmfaces)
+
+Call mask(fld,NaN)
+"""
 function mask(fld::gcmfaces)
 fldmsk=mask(fld,NaN)
 return fldmsk
 end
 
+"""
+    mask(fld::gcmfaces, val::Number)
+
+Replace non finite values with val
+"""
 function mask(fld::gcmfaces, val::Number)
   fldmsk=similar(fld)
   for a=1:fld.nFaces
@@ -64,6 +89,11 @@ function mask(fld::gcmfaces, val::Number)
   return fldmsk
 end
 
+"""
+    mask(fld::gcmfaces, val::Number)
+
+Replace noval instances with val
+"""
 function mask(fld::gcmfaces, val::Number, noval::Number)
   fldmsk=similar(fld)
   for a=1:fld.nFaces
@@ -76,7 +106,12 @@ end
 
 ## convergence methods
 
-function convergence(uFLD::gcmfaces,vFLD::gcmfaces);
+"""
+    convergence(uFLD::gcmfaces,vFLD::gcmfaces)
+
+Compute convergence of a vector field
+"""
+function convergence(uFLD::gcmfaces,vFLD::gcmfaces)
 
 #important note:
 #  Normally uFLD, vFLD should not contain any NaN;
@@ -100,6 +135,11 @@ end
 
 ## smooth function
 
+"""
+    smooth(FLD::gcmfaces,DXCsm::gcmfaces,DYCsm::gcmfaces)
+
+Smooth out scales below threshold
+"""
 function smooth(FLD::gcmfaces,DXCsm::gcmfaces,DYCsm::gcmfaces)
 
 #important note:

src/gcmfaces_convert.jl

@@ -1,6 +1,11 @@
 
 ## convert2array method:
 
+"""
+    convert2array(fld::gcmfaces)
+
+Convert gcmfaces to array
+"""
 function convert2array(fld::gcmfaces)
 
 if fld.grTopo=="llc";
@@ -23,6 +28,12 @@ return arr;
 end
 
 ## convert2array ##
+
+"""
+    convert2array(fld::Array{T,N}) where {T,N}
+
+Convert array to gcmfaces
+"""
 function convert2array(fld::Array{T,N}) where {T,N}
 
 grTopo=MeshArrays.grTopo;
@@ -58,6 +69,11 @@ end
 
 ## convert2gcmfaces method:
 
+"""
+    convert2gcmfaces(fld::gcmfaces)
+
+Convert mitgcm output to gcmfaces
+"""
 function convert2gcmfaces(fld::gcmfaces)
 
     grTopo=MeshArrays.grTopo;
@@ -90,6 +106,11 @@ end
 
 ## convert2gcmfaces ##
 
+"""
+    convert2gcmfaces(fld::Array)
+
+Convert gcmfaces to mitgcm output
+"""
 function convert2gcmfaces(fld::Array)
 
 grTopo=MeshArrays.grTopo;

src/gcmfaces_demo.jl

@@ -10,6 +10,11 @@
 # (Rini,Rend,DXCsm,DYCsm)=demo2();
 # @time Rend=smooth(Rini,DXCsm,DYCsm);
 
+"""
+    demo1(gridChoice)
+
+Demo overloaded arithmetic, exchange, GCMGridLoad, gradient, etc.
+"""
 function demo1(gridChoice)
 
 GCMGridSpec(gridChoice)
@@ -48,6 +53,11 @@ end
 
 ##
 
+"""
+    demo2()
+
+Demo at higher level using smooth()
+"""
 function demo2()
 
 #Pre-requisite:

src/gcmfaces_exch.jl

@@ -4,6 +4,15 @@
 
 ## User Front Ends
 
+"""
+    exchange(fld::gcmfaces)
+
+Exchange / transfer data between neighbor arrays. Other methods are
+
+    exchange(fld::gcmfaces,N::Integer)
+    exchange(u::gcmfaces,v::gcmfaces)
+    exchange(u::gcmfaces,v::gcmfaces,N::Integer)
+"""
 function exchange(fld::gcmfaces)
   FLD=exch_T_N(fld,1);
 end

src/gcmfaces_grids.jl

@@ -5,6 +5,12 @@ GCMGridSpec() = GCMGridSpec("LLC90")
 
 ## GCMGridSpec function with gridName argument:
 
+"""
+    GCMGridSpec(gridName)
+
+Set global variables in the module scope for grDir, nFaces, grTopo, ioSize,
+facesSize, ioPrec using hard-coded values for LLC90, CS32, LL360 (for now).
+"""
 function GCMGridSpec(gridName)
 
 global grDir, nFaces, grTopo, ioSize, facesSize, ioPrec;
@@ -40,6 +46,14 @@ end
 
 ## GCMGridLoad function
 
+"""
+    GCMGridLoad()
+
+Loads grid variables from files located in grDir set by GCMGridSpec.
+
+Grid variables are XC, XG, YC, YG, RAC, RAZ, DXC, DXG, DYC, DYG, hFacC,
+hFacS, hFacW, Depth based on the MITgcm naming convention.
+"""
 function GCMGridLoad()
 
     global XC, XG, YC, YG, RAC, RAZ, DXC, DXG, DYC, DYG, hFacC, hFacS, hFacW, Depth;
@@ -55,6 +69,11 @@ function GCMGridLoad()
 
 end
 
+"""
+    GCMGridOnes(grTp,nF,nP)
+
+Define all-1 grid variables instead of using GCMGridSpec & GCMGridLoad.
+"""
 function GCMGridOnes(grTp,nF,nP)
 
     global grDir, nFaces, grTopo, ioSize, facesSize, ioPrec;

src/gcmfaces_nctiles.jl

@@ -10,7 +10,12 @@ export read_nctiles
 #  Depth=read_nctiles(fileName,"Depth")
 #  hFacC=read_nctiles(fileName,"hFacC")
 
-function read_nctiles(fileName,fldName);
+"""
+    read_nctiles(fileName,fldName)
+
+Read model output from Netcdf / NCTiles file and convert to gcmfaces structure.
+"""
+function read_nctiles(fileName,fldName)
 
 if ~(MeshArrays.grTopo=="llc");
   error("non-llc cases not implemented yet");

src/gcmfaces_plot.jl

@@ -10,12 +10,22 @@ export qwckplot
 #  qwckplot(MeshArrays.Depth)
 #  qwckplot(MeshArrays.Depth,"Ocean Bottom Depth")
 
+"""
+    qwckplot(fld::gcmfaces)
+
+Call qwckplot(fld::gcmfaces,ttl::String) with current date for title
+"""
 function qwckplot(fld::gcmfaces)
     tmp1=Dates.now()
     tmp1=Dates.format(tmp1, "yyyy-mm-dd HH:MM:SS")
     qwckplot(fld,"Plotted at time "*tmp1)
 end
 
+"""
+    qwckplot(fld::gcmfaces,ttl::String)
+
+Plot input using convert2array and heatmap + add title
+"""
 function qwckplot(fld::gcmfaces,ttl::String)
     arr=convert2array(fld)
     arr=permutedims(arr,[2 1])

src/gcmfaces_type.jl

@@ -35,8 +35,7 @@ end
 ## additional constructors for gcmfaces
 
 """
-    gcmfaces(nFaces::Int,grTopo::String,::Type{T},
-      fSize::Array{NTuple{N, Int}},
+    gcmfaces(nFaces::Int,grTopo::String,::Type{T},fSize::Array{NTuple{N, Int}},
       aSize::NTuple{N,Int}) where {T,N}
 
 gcmfaces constructor.
@@ -152,7 +151,7 @@ end
 
 fsize convenience function.
 """
-function fsize(A::AbstractGcmfaces{T, N},i::Int) where {T,N}
+function fsize(A::AbstractGcmfaces{T, N}) where {T,N}
   fs=Array{NTuple{N, Int}}(undef,A.nFaces)
   for i=1:A.nFaces
     fs[i]=size(A.f[i]);
@@ -161,7 +160,7 @@ function fsize(A::AbstractGcmfaces{T, N},i::Int) where {T,N}
 end
 
 """
-    fsize(A::AbstractGcmfaces{T, N}) where {T,N}
+    fsize(A::AbstractGcmfaces{T, N},i::Int) where {T,N}
 
 fsize convenience function.
 """