Firstly, a trivial example (01.pav) - all this has to do is reflect the function signature
void main() {
}
This should generate output something like
Documentation for 01.pav
void main ()
A more ambitious example with five functions (02.pav)
void sort (int[] list, int size, bool ascending) {
}
void useStringBuffer(bool mayBeUseful) {}
int largest (int a, int b) {
}
bool isPresent (int[] list, int entry) {
}
void main() {
}
This should generate output with function signatures only, something like
Documentation for 02.pav
void sort (int[] list, int size, bool ascending)
void useStringBuffer (bool mayBeUseful)
int largest (int a, int b)
bool isPresent (int[] list, int entry)
void main ()
The next example shows the first application of the ParvaDoc comment (03.pav)
/** This shows a single ParvaDoc comment ahead of all functions
Essentially ANY sort of text is allowed in such comments
except for the key words like "@purpose" */
void main() {
}
This should generate output something like
Documentation for 03.pav
Purpose:
This shows a single ParvaDoc comment ahead of all functions
Essentially ANY sort of text is allowed in such comments
except for the key words like "@purpose"
void main ()
The next example (04.pav) shows simple ParvaDoc comments attached to functions. Note that these comments
can come just before or just after the opening brace, but essentially nowhere else.
/** This shows a single ParvaDoc comment ahead of all functions */
void inside() {
/** Shows a simple ParvaDoc comment inside a function after the opening brace */
}
void main()
/** Shows a simple ParvaDoc comment inside a main function ahead of the opening brace */
{
}
This should generate output something like
Documentation for 04.pav
Purpose:
This shows a single ParvaDoc comment ahead of all functions
void inside ()
Purpose:
Shows a simple ParvaDoc comment inside a function after the opening brace
void main ()
Purpose:
Shows a simple ParvaDoc comment inside a main function ahead of the opening brace
The next example has a few more directives (05.pav)
/** This shows a single ParvaDoc comment ahead of all functions
@author Pat Terry
@version 1000
*/
void inside() {
/** Shows a simple ParvaDoc comment inside a function after the opening brace
@version 123 - the latest one
*/
}
void main()
/** @purpose Shows a simple ParvaDoc comment inside a main function ahead of the opening brace
@author Pat Terry
*/
{
}
This should generate output something like
Documentation for 05.pav
Purpose:
This shows a single ParvaDoc comment ahead of all functions
Author:
Pat Terry
Version:
1000
void inside ()
Purpose:
Shows a simple ParvaDoc comment inside a function after the opening brace
Version:
123 - the latest one
void main ()
Purpose:
Shows a simple ParvaDoc comment inside a main function ahead of the opening brace
Author:
Pat Terry
Here is an example that has some errors (06.pav)
/** This shows a single ParvaDoc comment ahead of all functions
@author Pat Terry
@version 1000
@returns after lunch (but this should give an error message)
*/
void inside() {
/** if "@purpose" is omitted it is assumed by default - this one shows
a simple ParvaDoc comment inside a function after the opening brace
@version 123 - the latest one
*/
}
void main() {
/** @purpose Shows a simple ParvaDoc comment inside the main function
@author Pat Terry
@see "Light at the end of the tunnel"
@purpose We can add to a clause like purpose by giving the appropriate directive again
*/
}
However, this should still generate output something like
Documentation for 06.pav
Purpose:
This shows a single ParvaDoc comment ahead of all functions
Author:
Pat Terry
Version:
1000
void inside ()
Purpose:
if "@purpose" is omitted it is assumed by default - this one shows
a simple ParvaDoc comment inside a function after the opening brace
Version:
123 - the latest one
void main ()
Purpose:
Shows a simple ParvaDoc comment inside the main function
We can add to a clause like purpose by giving the appropriate directive again
Author:
Pat Terry
References:
"Light at the end of the tunnel"
The next example may clarify some other points (07.pav)
void three (int a, int b, bool c) {
/**
@param a is the first parameter
@param b is the second parameter
@param c is the third parameter
@purpose This shows how parameters may be described
*/
}
void main() {
}
This should generate output something like
Documentation for 07.pav
void three (int a, int b, bool c)
Purpose:
This shows how parameters may be described
Parameters:
a is the first parameter
b is the second parameter
c is the third parameter
void main ()
The next example shows the correct use of @return (08.pav)
int three (int a, int b, int c) {
/**
@param a is the first parameter
@param b is the second parameter
@param c is the third parameter
@purpose This shows how parameters may be described
@return sum of the parameters
*/
return (a + b + c);
}
void main() {
}
This should generate output something like
Documentation for 08.pav
int three (int a, int b, int c)
Purpose:
This shows how parameters may be described
Returns:
sum of the parameters
Parameters:
a is the first parameter
b is the second parameter
c is the third parameter
void main ()
But the next example should lead to error messages (09.pav)
void three (int a, int b, int c) {
/**
@param a is the first parameter
@param b is the second parameter
@param c is the third parameter
@purpose This shows how parameters may be described
@return sum of the parameters - this should give an error message
*/
return;
}
void main() {
}
However, this should generate output something like
Documentation for 09.pav
void three (int a, int b, int c)
Purpose:
This shows how parameters may be described
Returns:
sum of the parameters - this should give an error message
Parameters:
a is the first parameter
b is the second parameter
c is the third parameter
void main ()
Any parameters mentioned in @param clauses should also appear in the function signature (10.pav)
void three (int a, int b, bool c) {
/**
@param a is the first parameter
@param b is the second parameter
@param c is the third parameter
@param d should not be mentioned - should give an error message
@param e should not be mentioned either - another error message
@param a has been mentioned again
*/
}
void main() {
}
This should generate output something like
Documentation for 10.pav
void three (int a, int b, bool c)
Parameters:
a is the first parameter
b is the second parameter
c is the third parameter
d should not be mentioned - should give an error message
e should not be mentioned either - another error message
a has been mentioned again
void main ()
Parameters can be of various types (11.pav)
void three (int[] list, int n, bool c) {
/**
@purpose Shows that parameters can be of reference types
@param list is a reference to a list
@param n gives the length of the list
@param c specifies whether the list is full
*/
}
void main() {
}
This should generate output something like
Documentation for 11.pav
void three (int[] list, int n, bool c)
Purpose:
Shows that parameters can be of reference types
Parameters:
list is a reference to a list
n gives the length of the list
c specifies whether the list is full
void main ()
ParvaDoc comments cannot appear in arbitrary places (12.pav)
/**
@author P.D. Terry, Rhodes University, 2005
@return cannot be used in the overall description
@param cannot be used in the overall description
*/
void ProcessList(int[] list, int n, int length) {
/**
@param max does not appear in the parameter list so this is meaningless
@return is meaningless here as void functions do not return values
*/
}
/** These sorts of comments cannot appear in arbitrary places between functions! */
This should generate output something like
Documentation for 12.pav
Author:
P. D. Terry, Rhodes University, 2005
void ProcessList (int[] list, int n, int length)
Returns:
is meaningless here as void functions do not return values
Parameters:
max does not appear in the parameter list so this is meaningless
Here is an example with a whole lot of errors! (13.pav)
/**
Note that if the "@purpose" keyword is missing the text is taken to be a comment on the
purpose of the program or function.
@author P.D. Terry, Rhodes University, 2005
@version This version illustrates various errors that might be made
using the ParvaDoc system
@return cannot be used in the overall description
@param cannot be used in the overall description
*/
int ProcessList(int[] list, int n, int length) {
/**
@param max does not appear in the parameter list so this is meaningless
*/
// omitted the body for demonstration putposes
}
int GenerateList(int[] list, int max) {
// Some programmers put the opening brace immediately after the parameter list
}
int[] NewList(int max) {}
void main()
/** Driver program for demonstration program
@return is meaningless in a void function and should not be allowed
@param N is meaningless as this particular function has no parameters
*/
// Some programmers put the opening brace on a line of its own
{
write("This programme does nothing useful!");
}
/** These sorts of comments cannot appear in arbitrary places between functions! */
But here is an example that has ordinary comments in spite of what you might think (14.pav)
/* No, this is not a ParvaDoc comment! */
// Pragmatically, these sorts of comments can appear in arbitrary places
void ProcessList(int[] list, int n, int length) {
// This is another of the sorts of comment that should be ignored
}
This should generate output as simple as the following, as those comments all get ignored
Documentation for 14.pav
void ProcessList (int[] list, int n, int length)
Finally, here is a real example for you to test your ideas in detail (textluck.pav)
/**
Simple test bed program for checking on the generation of lucky numbers
@author P.D. Terry, Rhodes University, 2005
@version This version illustrates various features of the ParvaDoc system
*/
int ReduceLength(int[] list, int n, int length) {
/** @purpose Reduces a list of integer numbers by removing every n-th number
@param length specifies the original length of the list
@return length of reduced list
@param n specifies that every n-th number is to be removed
@see "Algorithms for a Special Sunday" (2005)
@param list is a reference to the list of numbers
@version 1234
@author PDT with a little help from my friends
John
Paul
George
Ringo
*/
int copied = 0;
int i = 1;
while (i <= length) {
if (i - (i / n) * n != 0) { // if i % n == 0 we would remove it
list[copied] = list[i-1];
copied = copied + 1;
}
i = i + 1;
}
return copied;
}
int GenerateLuckyNumbers(int[] list, int max) {
/** @purpose Generate a list of the lucky numbers between 1 and max (inclusive)
@see For a description of which numbers are deemed to be lucky, see the course
web page, and in particular Practical 19
@param list is a reference to the generated list
@param max is the limit on the maximum possible lucky number
@return the length of the list
*/
int step = 2;
int length = max;
while (step <= length) {
length = ReduceLength(list, step, length);
step = step + 1;
}
return length;
}
int[] NewList(int max) {
/** Allocate and initialise a list of integers
@param max is the length of the list
@return a reference to list such that list[i] = i + 1 for i = 0 .. max-1
*/
int[] list = new int[max];
int i = 0;
while (i < max) {
list[i] = i + 1;
i = i + 1;
}
return list;
}
void main()
/** Driver program for lucky number sieve program */
// some people put the opening brace on a line of its own
{
int limit;
read("Supply limit of numbers to be tested for luck ", limit);
int[] luckyList = NewList(limit);
int n = GenerateLuckyNumbers(luckyList, limit);
int i = 0;
while (i < n) {
write(luckyList[i], "\t");
i = i + 1;
}
}
This should generate output something like
Documentation for textluck.pav
Purpose:
Simple test bed program for checking on the generation of lucky numbers
Author:
P. D. Terry, Rhodes University, 2005
Version:
This version illustrates various features of the ParvaDoc system
int ReduceLength (int[] list, int n, int length)
Purpose:
Reduces a list of integer numbers by removing every n - th number
Author:
PDT with a little help from my friends
John
Paul
George
Ringo
Version:
1234
References:
"Algorithms for a Special Sunday" (2005)
Returns:
length of reduced list
Parameters:
length specifies the original length of the list
n specifies that every n - th number is to be removed
list is a reference to the list of numbers
int GenerateLuckyNumbers (int[] list, int max)
Purpose:
Generate a list of the lucky numbers between 1 and max (inclusive)
References:
For a description of which numbers are deemed to be lucky, see the course
web page, and in particular Practical 19
Returns:
the length of the list
Parameters:
list is a reference to the generated list
max is the limit on the maximum possible lucky number
int[] NewList (int max)
Purpose:
Allocate and initialise a list of integers
Returns:
a reference to list such that list [ i ] = i + 1 for i = 0.. max - 1
Parameters:
max is the length of the list
void main ()
Purpose:
Driver program for lucky number sieve program
An excellent idea might be to allow for HTML to be generated. You can look at possible HTML output from the
previous examples by following the links from the index.htm page in the kit.
Here is an extended example that incorporates user defined tags (htmlluck.pav) Again, you can see the sort of
output this might generate in the file htmlluck.htm in the kit.
/**
Simple test bed program for checking on the generation of lucky numbers
- this version shows how HTML tags might be introduced
@author
@<a href=mailto:p.terry@ru.ac.za>P.D. Terry@</a>,
@<a href=http://www.ru.ac.za>Rhodes University@</a>, 2005
@version This version illustrates various features of the ParvaDoc system
*/
int ReduceLength(int[] list, int n, int length) {
/** Reduces a list of integer numbers by removing every n-th number
@param length specifies the original length of the list
@return length of reduced list
@param n specifies that every n-th number is to be removed
@see @<a href=sunday.htm>"Algorithms for a Special Sunday" (2005)@</a>
@author PDT @<i>with a little help from my friends@</i>@<ul>
@<li>John
@<li>Paul
@<li>George
@<li>Ringo
@</ul>
*/
int copied = 0;
int i = 1;
while (i <= length) {
if (i - (i / n) * n != 0) { // if i % n == 0 we would remove it
list[copied] = list[i-1];
copied = copied + 1;
}
i = i + 1;
}
return copied;
}
int GenerateLuckyNumbers(int[] list, int max) {
/** @purpose Generate a list of the lucky numbers between 1 and max (inclusive)
@see For a description of which numbers are deemed to be lucky, see the
@<a href=http://www.cs.ru.ac.za/courses/CSC301/Translators/trans.htm>course
web page@</a>, and in particular
@<a href=http://www.cs.ru.ac.za/courses/CSC301/Translators/prac19.htm>
Practical 19@</a>
@param list is a reference to the generated list
@param max is the limit on the maximum possible lucky number
@return the length of the list
*/
int step = 2;
int length = max;
while (step <= length) {
length = ReduceLength(list, step, length);
step = step + 1;
}
return length;
}
int[] NewList(int max) {
/** Allocate and initialise a list of integers
@param max is the length of the list
@return a reference to list such that list[i] = i + 1 for i = 0 .. max-1
*/
int[] list = new int[max];
int i = 0;
while (i < max) {
list[i] = i + 1;
i = i + 1;
}
return list;
}
void main()
/** Driver program for lucky number sieve program */
// some people put the opening brace on a line of its own
{
int limit;
read("Supply limit of numbers to be tested for luck ", limit);
int[] luckyList = NewList(limit);
int n = GenerateLuckyNumbers(luckyList, limit);
int i = 0;
while (i < n) {
write(luckyList[i], "\t");
i = i + 1;
}
}
Home © P.D. Terry