Documenting automated Scripts

Recently a colleague (new to our team) asked me the documentation for our suite. I do not have any document or HELP files. Earlier My team thought about it and one member came with a silktest script to do that. We have to add more features like search, organizing by attributes. That utility did not give the most needed feature. To ease the documentation job, we need to use set of tags and detailed info for them. We are unable to follow this more than a week.

Most of the automated testing tools are not having documenting facility. I am expecting similar to PerlDoc (for Perl scripts) or JavaDoc (for Java). It is the duty of script developer to ensure the adequate comments for particular function or code block. I used to put two or three line comments, While writing the functions.

Generally these kind of tools or utilities, have a parser. It can parse the source code and get the details by the pre-defined tags or keywords. Then It creates the HELP files for each code block or script. The usage will be meaningful if documentation is regularly updated. Now most utilities are creating HTML files and it is easy to navigate and share the information. I was going through J2Se doc comments. JavaDoc is having the flexibility of including HTML tags.