% Template for m-file (header/help block with full documentation of file)
%
% This m-file contains two features:
% - a fully documented template for documenting m-files
% - a real template applicable to be copied into own m-files (find it at 
%   the end of this file)
% The first part is used to describe all the elements of a well-documented
% m-file. It represents my working style (a result of 6+ years of matlab
% experience, including developing the http://www.GEATbx.com/). 
% Nevertheless, it reflects my personal opinion. I am always open to
% suggestions, enhancements and discussions (mailto:hartmut@pohlheim.com).
% The second part can be copied into your own m-files and you can fill out 
% the blanks, giving you a head-start.
%
%
% Structure and Elements of a well-documented m-file:
% 
% The first comment line in the m-file should contain a short one-line 
% description of the purpose of the m-file. This short description is 
% used in the automatically generated docu with Perl script.
% 
% The next block of text should provide an extensive description 
% of the full functionality of the m-file. 
% Simple functions use only 3-4 lines of text, more complex functions 
% even more than 50 lines. 
%
% Please remember that the complete first help block is displayed
% when calling "help" for the m-file. Thus, even empty comment lines 
% must start with a % sign. 
%
% The following Syntax line gives a short hand overview of the calling 
% syntax (number and names of input and output parameters) of the m-file.
%
% Syntax:  [FirstParaOut, SecondParaOut] = nameofmfile(FirstParaIn, SecondParaIn, ThirdParaIn)
%
% Very important is the full documentation of all input and output parameters.
% Please provide as much information as possible:
%  - is the parameter optional (add an (optional) at the beginning of 
%    the parameter description)
%  - the data type of the parameter (scalar, row/column vector, matrix, 
%    cell array, structure, ...  or any combination of them)
%  - if a parameter has only a limited set of possible values (option 
%    values), here is the place to document them. See the examples below.
% 
% [here an example from the GEATbx, do not look for the content, just 
%  the amount/design of provided information]
% Input parameters:
%    PopInit   - Vector or matrix containing the initial individuals
%                   may be any number of individuals
%                if PopInit is empty, a uniform at random initialization
%                   of individuals takes place
%    Nind      - Scalar containing the number of individuals to create at all
%    VLUB      - (optional) Matrix containing the boundaries of the variables
%    InitOpt   - (optional) Scalar or vector containing the parameters for initialization
%                InitOpt(1): InitRand
%                            level of randomization of (inoculated) individuals
%                            0: no randomization, no similar individuals are produced
%                           >0: randomize individuals using the following equation
%                               (randn/4 * InitRand * domain of variable)
%                            standard: 0.25
%                InitOpt(2): InitNindKeep
%                            keep preinitialized individuals in population (unchanged)
%                            0: keep none of them
%                            > 0 (max 1): scalar (percentage of population size) how 
%                               many individuals from PopInit to copy to Chrom
%                            standard: 0.2 (keep not more than 20% of individuals
%                                      in final population)
%                InitOpt(3): InitNindUniform
%                            create some individuals uniform at random in defined 
%                            domain of variables (boundaries VLUB) - uses the 
%                            standard init functions initrp, initip, initbp and initpp
%                            0: create none
%                            > 0 (max 1): scalar (percentage of population size) how 
%                            standard: 0 (create no individuals uniform at random)
%                               many individuals to create uniform at random
%
% Output parameters:
%    Chrom     - Matrix containing the individuals of the current
%                population. Each row corresponds to one individual's
%                representation.
%    VLUB      - (optional) Matrix containing the (new) boundaries of the 
%                variables 
%
% Examples:
%
% % Short description of example, followed by Matlab code line
% % one example may show a very simple call of the function
% >> newpop = initpop([], 25, vlub)
%
% % the second+ examples show more extended variants
% % try to cover all significant different uses of the function
% >> newpop = initpop(popinit, 60, vlub, [0, 0.4, 1, 0.5]);
%
% The "See also:" line is important for cross references. Mathworks applies 
% this for many years now and it is very useful in everyday work.
% Additionally, the automatic documentation generation by the Perl script 
% creates hyperlinks from the See also: entries.
%
% See also: prprintf, findfiles, straddtime

% The last block contains info on author and history of the function.
% It is often very useful to know when something changed and who changed it.
% The author and history block is divided by an empty line from the first 
% help block. So this block is not displayed when calling for help on the
% matlab command line.
%
% Author:   Hartmut Pohlheim
% History:  12.11.2000  file created
%                       full description at the top
%           19.11.2000  suggestions for in-code comments added


function [Chrom, VLUB] = initpop(PopInit, Nind, VLUB, InitOpt)

% Some general suggestions regarding comments in m-files:
%    In my opinion each source code block should get a purpose description 
%    at the beginning. This description contains information about what 
%    this block does and indicates special cases.
%    It would even be better is to comment almost every line - except when
%    the purpose is very clear. Remember, the code should be readable even
%    for other people (and yourself a few month later).

% A "well-behavioural" m-file should first check:
% - if all necessary input parameters are provided (if not, error),
% - set the not provided and optional input parameters to their default values,
% - check, whether input parameters are inside their boundaries, correct 
%   possible errors as far as possible and issue only a warning (not an error).
% Then all the later code can work without checking for existence or 
% compliance of the input paramneter values.


% Set standard initialization parameter
   InitOptStandard = [0.2, 0.25, 0];
   % InitRand = 0.3 (use normal random inoculation with 30% of domain of variables),
   % InitNindKeep = 0.2 (keep 20% maximal)
   % InitNindUniform = 0 (create no random individuals)

% Check input parameters
   % At least the first 2 input parameters are necessary
   if nargin < 2,  error('Not enough input parameters (at least 2 parameters - individuals and Nind)'); end
   if isnan(PopInit), PopInit = []; end
   % The 3. input parameter is optional, default is []
   if nargin < 3,  VLUB = []; end

   % the 4. input parameter is optional and can contain multiple options
   if nargin < 4, InitOpt = []; end
   if isnan(InitOpt), InitOpt = []; end
   % When too many options are contained in InitOpt, issue a warning and 
   % shorten the parameter vector
   if length(InitOpt) > length(InitOptStandard), 
      InitOpt = InitOpt(1:length(InitOptStandard)); 
      warning(' Too many parameters in InitOpt! InitOpt was shortened.');
   end

   % and so on
   

% End of function




% Here is the template for a well-documented m-file


% Short one line description
%
% Exhaustive and long description of functionality of m-file.
% 
% Syntax:  [ParaOut] = nameofmfile(ParaIn)
%
% Input parameters:
%    ParaIn    - Vector or matrix containing the initial individuals
%                   may be any number of individuals
%                if PopInit is empty, ...
%    ParaIn2   - (optional) Scalar or vector containing ...
%                ParaIn2(1): InitRand (name of option)
%                            short description of option
%                            0: ...
%                            >0: ...
%                            standard: 0.25
%
% Output parameters:
%    ParaOut   - description
%    ParaOut2  - (optional) description
%
% Examples:
%
% % Short description of example, followed by Matlab code line
% >> matlab code of example
%
% See also: prprintf, findfiles, straddtime

% Author:   Hartmut Pohlheim
% History:  12.11.2000  file created
%                       full description at the top
%           19.11.2000  suggestions for in-code comments added


function [ParaOut] = nameofmfile(ParaIn)

% Check input parameters



% End of function
