Improvement of help messages

In some of our help messages we have some redundancy, which we might improve on. For example, the output of help circexp_mono_ps:

 CIRCEXP_MONO_PS calculates the circular basis expansion of a point source

    Usage: Pm = circexp_mono_ps(xs,Nce,f,xq,[fhp],conf)

    Input parameters:
        xs      - position of point source / m [1 x 3]
        Nce     - maximum order of circular basis expansion
        f       - frequency of the monochromatic source / Hz
        xq      - expansion center / m [1 x 3]
        fhp     - cut-off frequency of highpass for regularisation / Hz
        conf    - configuration struct (see SFS_config)

    Output parameters:
        Pm      - regular circular expansion coefficients
                  for m = 0:Nce, [1 x Nce+1]

    CIRCEXP_MONO_PS(xs,Nce,f,xq,fhp,conf) returns the circular basis expansion
    of a point source.

    See also: circexp_mono_pw

As you can see the first line with CIRCEXP_MONO_PS and the line with CIRCEXP_MONO_PS(xs,Nce,f,xq,fhp,conf) are nearly identical. Of course this is not always the case, for some functions the fist line is very short and the line after Output parameters contains a long explanation.

I see two ways of improving the situation:

1.) Removing all first lines and always start with an empty line followed by Usage. This will always work, independent of the length of the description.


    Usage: Pm = circexp_mono_ps(xs,Nce,f,xq,[fhp],conf)

    Input parameters:
        xs      - position of point source / m [1 x 3]
        Nce     - maximum order of circular basis expansion
        f       - frequency of the monochromatic source / Hz
        xq      - expansion center / m [1 x 3]
        fhp     - cut-off frequency of highpass for regularisation / Hz
        conf    - configuration struct (see SFS_config)

    Output parameters:
        Pm      - regular circular expansion coefficients
                  for m = 0:Nce, [1 x Nce+1]

    CIRCEXP_MONO_PS(xs,Nce,f,xq,fhp,conf) returns the circular basis expansion
    of a point source.

    See also: circexp_mono_pw

2.) Removing the second description if it is not longer than the first line. This would leave it in for more complex functions like time_response_localwfs_vss(). Some functions behave already like this, e.g. driving_function_mono_localwfs_sbl().

 CIRCEXP_MONO_PS calculates the circular basis expansion of a point source

    Usage: Pm = circexp_mono_ps(xs,Nce,f,xq,[fhp],conf)

    Input parameters:
        xs      - position of point source / m [1 x 3]
        Nce     - maximum order of circular basis expansion
        f       - frequency of the monochromatic source / Hz
        xq      - expansion center / m [1 x 3]
        fhp     - cut-off frequency of highpass for regularisation / Hz
        conf    - configuration struct (see SFS_config)

    Output parameters:
        Pm      - regular circular expansion coefficients
                  for m = 0:Nce, [1 x Nce+1]

    See also: circexp_mono_pw

@fietew: any opinion on this?

sfstoolbox / sfs-matlab

Improvement of help messages #172