Project

General

Profile

Using Docblocks for quality code documentation » History » Version 34

Simon Hodgkiss, 01/22/2010 03:03 PM

1 1 Simon Hodgkiss
h1. Using Docblocks for quality code documentation
2 2 Simon Hodgkiss
3 22 Simon Hodgkiss
h2. Important information to developers
4 1 Simon Hodgkiss
5 32 Simon Hodgkiss
The way in which each file should be documented has changed slightly. You may have already seen some changes to a few of the files already. Here you will find all the references you will need to keep your files to the new standards of the Docblock documentation. 
6 1 Simon Hodgkiss
7 27 Simon Hodgkiss
    1. The top Docblock should stay the same in all files.
8 1 Simon Hodgkiss
9 27 Simon Hodgkiss
    2. The top copyright is to stay the same.
10 23 Simon Hodgkiss
11 27 Simon Hodgkiss
    3. The minimum Docblock you should use has to have at least: A Description, @package    VirtueMart and an @author.
12 18 Simon Hodgkiss
13 33 Simon Hodgkiss
h3. Optional Document Tags 
14 28 Simon Hodgkiss
 
15 1 Simon Hodgkiss
You can add the @copyright into the docblock above any of code your wish to add additional copyright to.
16 33 Simon Hodgkiss
17 1 Simon Hodgkiss
If you do not require all the @tags when documenting your code feel free to take them out as long as it meets the minimum requirements.
18 34 Simon Hodgkiss
19 34 Simon Hodgkiss
h3. List of Document Tags
20 34 Simon Hodgkiss
21 34 Simon Hodgkiss
@package
22 34 Simon Hodgkiss
@subpackage 
23 34 Simon Hodgkiss
@author
24 34 Simon Hodgkiss
@link
25 34 Simon Hodgkiss
@copyright
26 34 Simon Hodgkiss
@license
27 34 Simon Hodgkiss
@author
28 34 Simon Hodgkiss
@access
29 34 Simon Hodgkiss
@todo
30 34 Simon Hodgkiss
@see
31 34 Simon Hodgkiss
@param 		
32 34 Simon Hodgkiss
@return
33 8 Simon Hodgkiss
34 29 Simon Hodgkiss
h3. Sample files
35 4 Simon Hodgkiss
36 4 Simon Hodgkiss
I have provided you with two files for each type one which has comments on how the document tags work and which should be used.
37 4 Simon Hodgkiss
The other is a blank file which has the basic template for you to drop any code into.
38 7 Simon Hodgkiss
39 30 Simon Hodgkiss
40 11 Simon Hodgkiss
41 11 Simon Hodgkiss
42 11 Simon Hodgkiss
43 11 Simon Hodgkiss
44 11 Simon Hodgkiss
45 11 Simon Hodgkiss
46 11 Simon Hodgkiss
47 11 Simon Hodgkiss
48 11 Simon Hodgkiss
49 11 Simon Hodgkiss
50 11 Simon Hodgkiss
...