% 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