Add docstrings and Update comments

Author: kimikage

src/FixedPointNumbers.jl

@@ -10,8 +10,14 @@ import Base: ==, <, <=, -, +, *, /, ~, isapprox,
 
 using Base: @pure
 
-# T => BaseType
-# f => Number of bits reserved for fractional part
+"""
+    FixedPoint{T <: Integer, f} <: Real
+
+Supertype of the two fixed-point number types: `Fixed{T, f}` and `Normed{T, f}`.
+
+The parameter `T` is the underlying machine representation and `f` is the number
+of fraction bits.
+"""
 abstract type FixedPoint{T <: Integer, f} <: Real end
 
 

src/fixed.jl

@@ -1,5 +1,16 @@
-# 32-bit fixed point; parameter `f` is the number of fraction bits
-struct Fixed{T <: Signed,f} <: FixedPoint{T,  f}
+"""
+    Fixed{T <: Signed, f} <: FixedPoint{T, f}
+
+`Fixed{T,f}` maps `Signed` integers from `-2^f` to `2^f` to the range
+[-1.0, 1.0]. For example, `Fixed{Int8,7}` maps `-128` to `-1.0` and `127` to
+`127/128 ≈ 0.992`.
+
+There are the typealiases for `Fixed` in the `QXfY` notation, where `Y` is
+the number of fractional bits (i.e. `f`), and `X+Y+1` equals the number of
+underlying bits used (`+1` means the sign bit). For example, `Q0f7` is aliased
+to `Fixed{Int8,7}` and `Q3f12` is aliased to `Fixed{Int16,12}`.
+"""
+struct Fixed{T <: Signed, f} <: FixedPoint{T, f}
     i::T
 
     # constructor for manipulating the representation;
@@ -37,7 +48,7 @@ abs(x::Fixed{T,f}) where {T,f} = Fixed{T,f}(abs(x.i),0)
 -(x::Fixed{T,f}, y::Fixed{T,f}) where {T,f} = Fixed{T,f}(x.i-y.i,0)
 
 # with truncation:
-#*{f}(x::Fixed32{f}, y::Fixed32{f}) = Fixed32{f}(Base.widemul(x.i,y.i)>>f,0)
+#*(x::Fixed{T,f}, y::Fixed{T,f}) = Fixed{T,f}(Base.widemul(x.i,y.i)>>f,0)
 # with rounding up:
 *(x::Fixed{T,f}, y::Fixed{T,f}) where {T,f} = Fixed{T,f}((Base.widemul(x.i,y.i) + (one(widen(T)) << (f-1)))>>f,0)
 

src/normed.jl

@@ -1,7 +1,16 @@
-# Normed{T,f} maps UInts from 0 to 2^f-1 to the range [0.0, 1.0]
-# For example, Normed{UInt8,8} == N0f8 maps 0x00 to 0.0 and 0xff to 1.0
-
-struct Normed{T<:Unsigned,f} <: FixedPoint{T,f}
+"""
+    Normed{T <: Unsigned, f} <: FixedPoint{T, f}
+
+`Normed{T,f}` maps `Unsigned` integers from `0` to `2^f-1` to the range
+[0.0, 1.0]. For example, `Normed{UInt8,8}` maps `0x00` to `0.0` and `0xff` to
+`1.0`.
+
+There are the typealiases for `Normed` in the `NXfY` notation, where `Y` is
+the number of fractional bits (i.e. `f`), and `X+Y` equals the number of
+underlying bits used. For example, `N0f8` is aliased to `Normed{UInt8,8}` and
+`N4f12` is aliased to `Normed{UInt16,12}`.
+"""
+struct Normed{T <: Unsigned, f} <: FixedPoint{T, f}
     i::T
 
     Normed{T, f}(i::Integer,_) where {T,f} = new{T, f}(i%T)   # for setting by raw representation