HOME | Research | Media | Careers | Contacts | Products | Search | Publications | Site Map

CSIRO Mathematics, Informatics and Statistics

Image Analysis Biotech Imaging Group Application Areas  Biotechnology  Cellular Screening  Health  Asset Monitoring  Exploration  Other Areas Skills  Segmentation  Feature Extraction  Statistical Analysis  Stereo Vision  Image Motion   Projects Imaging Services Imaging Products Track Record Publications Patents Staff

LIAR function documentation LIAR functions need to be documented, but the question is how to achieve this task without having to perform multi-edits or any arduous task that would be offputting to the average programmer. Therefore, the philosophy we have adopted is to use the C programming language as far as possible to express the documentation in the form of source code comments, which have been strategically place in the source file. This then means that the documentation and the source code are bounded together in one file; thus, facilitating documentation and source code updates to occur simultaneously. The LIAR strategy is then to pipe the souce code files through c2man, which extracts the appropriate comment blocks into various forms of output; such as, man pages, web pages, LaTeX documents, etc. Here, we will essentially be concerned with producing Unix man pages outputs. As an example, consider the following C function: darray_t * reflectContour(darray_t * d, int xaxis, int yaxis) { darray_t * new = crt_darray(sizeof(point2D_t),getmod(d)); point2D_t *p = getdata(d), pdc; int i,j,n = getnumitems(d); for(j=0;j<n;++j,++p) { if(xaxis) pdc.x = -p->x; else pdc.x = p->x; if(yaxis) pdc.y = -p->y; else pdc.y = p->y; push_last(new,&pdc); } return new; } The above function would then be documented by placing a comment after each parameter in the function heading and by adding the standard LIAR comment block immediate after the first opening curly bracket, {, of the function: darray_t * reflectContour(darray_t * d, /* Darray holding the contour points */ int xaxis, /* if not zero reflect on 'x' axis */ int yaxis) /* if not zero reflect on 'y' axis */ { /** reflect the contour about the x or y axis RETURN VALUE: darray_t *, which holds the reflected contour DESCRIPTION: This function will reflect the contour points in `d' about either the x-axis or y-axis or even both -- depending upon the flag values: xaxis and yaxis. HISTORY: Written by Ed. Breen TESTS: Tested on various contours and used extensively. KEYWORDS: geometry REFERENCES: **/ darray_t * new = crt_darray(sizeof(point2D_t),getmod(d)); point2D_t *p = getdata(d), pdc; int i,j,n = getnumitems(d); for(j=0;j<n;++j,++p) { if(xaxis) pdc.x = -p->x; else pdc.x = p->x; if(yaxis) pdc.y = -p->y; else pdc.y = p->y; push_last(new,&pdc); } return new; } Note, the first line of the LIAR comment block holds a one liner, which briefy describes the function and that each section in the comment block is preceded by a blank line and the title of the each section starts with an uppercase word followed by a colon. The fields or sections in the LIAR comment block are further explained in Table 3.   Once the function has been documented, it is then piped through c2man: % c2man -b -I/include_directories contour.c where contour.c is the file that holds the function reflectContour, plus possibly other documentated functions, and the include_directories is used to specify any include directories that the source file may be dependent on; for example, /home/liar/include. The above command will produces a man page such as: reflectContour reflectContour NAME reflectContour - reflect the contour about an axis SYNOPSIS darray_t *reflectContour ( darray_t *d, int xaxis, int yaxis ); PARAMETERS darray_t *d Darray holding the contour points. int xaxis If not zero reflect on 'x' axis. int yaxis If not zero reflect on 'y' axis. DESCRIPTION This function will reflect the contour points in `d' about either the x-axis or y-axis or even both -- depending upon the flag values: xaxis and yaxis. RETURN VALUE Darray_t *, which holds the reflected contour. HISTORY Written by Ed. Breen. TESTS Tested with various contours and used extensively. KEYWORDS Geometry SEE ALSO get_C_MaxMinVals, rotateContour, connectContour, get_C_MER which is then moved into the LIAR man page home directory, or some other suitable place. This is then followed by the catman(1) command, which is used to update the man index files, etc: % mv *.3 /home/liar/man/man3 % catman -M/home/liar/man/man3 LIAR Keywords LIAR referencing style

© Copyright 2013, CSIRO Australia
Use of this web site and information available from
it is subject to our Legal Notice and Disclaimer and Privacy Statement