Creating Script Documentation by Using Comments

Microsoft® Windows® 2000 Scripting Guide

microsoft windows 2000 scripting guide

« Previous | Next »   

Scripts are often short pieces of code designed to carry out a single function. Because of this, formal documentation is not always required; the script comments usually provide sufficient information for anyone using the script. For longer scripts, however, it might be useful to provide separate documentation rather than requiring users to read through the script, searching for comments.

Well-commented scripts can actually help you write the documentation for your scripts. By including comments such as who wrote the script, when it was written, why it was written, and the purpose of procedures and functions, you already have much of the written documentation for the script as well. You only need to copy those comments from the script to the script documentation.

One way to create separate documentation for a script is to use an automated procedure to extract the comments. These comments can then serve as the basis for the written documentation. For example, the script shown in Listing 18.2 extracts comments by doing the following:

  • Opens a script file (C:\Scripts\SystemMonitor.vbs).
  • Reads through each line of the script, looking for comments. These are readily identifiable because the script uses a unique identifier ( *) to delineate comments.
  • Saves the line to a text file (C:\Scripts\Comments.txt) if the line is a comment. If the line is not a comment, the script proceeds to the next line of the script file. This process continues until all the lines in SystemMonitor.vbs are read and processed.

Listing 18.2   Extracting Comments

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 
Const ForReading = 1 Const ForWriting = 2 Set objFSO = CreateObject("Scripting.FileSystemObject") Set objScriptFile = objFSO.OpenTextFile _     ("c:\scripts\Service_Monitor.vbs", ForReading) Set objCommentFile = objFSO.OpenTextFile("c:\scripts\Comments.txt", _     ForWriting, TRUE) Do While objScriptFile.AtEndOfStream <> TRUE     strCurrentLine = objScriptFile.ReadLine     intIsComment = Instr(1,strCurrentLine,"'*")     If intIsComment > 0 Then         objCommentFile.Write strCurrentLine & VbCrLf     End If Loop objScriptFile.Close objCommentFile.Close

send us your feedback Send us your feedback « Previous | Next »   


Microsoft Windows 2000 Scripting Guide(c) Automating System Administration 2003
Microsoft Windows 2000 Scripting Guide(c) Automating System Administration 2003
ISBN: N/A
EAN: N/A
Year: 2004
Pages: 635

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net