Introducing VDK Doc comments
Its nice using other people's code but whats not nice is having to dig into that code to understand how to use it. Thats an instant mood killer! Thats why we have VDK doc comments to the rescue!
VDK Doc comments come standard with the VDK core install to help you easily incorporate the VDK into your everyday scripting needs.
Doc comments come in 2 flavours; Class level doc comment and procedure level doc comments. Here's a sample from the vdk.lang.clsFile class:
Class clsFile
'/**
'This class is the base class for all file operations. The class uses the native
''FileSystemObject' functionality to access the Windows file system.
'
'In the VDK world, the concept of a file differs from the commonly known system.filesystem object.
'In FSO, a distinct difference is made between file and folder and you would use different methods to
'test and access it. This is different to the VDK as the VDK follows the Unix methodology where
'every path on the underlying file system, is a file irrespective of whether the Windows OS treats it
'as a file or directory. In other words, "c:\windows" is a file, "c:\temp\jason.txt" is a file, "d:\documents and settings"
'is a file, etc.
'
'This class does not care if the path exists or not on the file system.
'The Path is treated like an abstract path. Any method called
'is called on the path and then on the actual underlying file (if it exists). As an example, if you call delete
'on the path of this class, then the delete method will first interrogate the path to make sure
'its valid. If the path is valid, then an attempt to delete the file on the underlying windows system will
'be made. Whether the file exists or not is immaterial.
'
'Also keep in mind that this class treats a
'file like a container. This class only knows about the container. It knows absolutely nothing
'about what's in the container. Hence, this class can create, delete,
'move, copy or get Attributes on the container but it can't tell you what's inside the container. The inside of the
'container is a black box.
'
'If you need to do operations on the content of the container, then you need to look at
'the {@link vdk.io.clsFileUtils} as well as other classes in the {@link vdk.io} package that handle
'reading and writing of container/file content.
'
'@Author Jason Ely
'@version 1
'@since 1
'@see vdk.io.clsFileUtils
'/
Private FOR_READING
Private FOR_WRITING
Private FOR_APPENDING
Private objFSO
private strFilePath
private objThisFile 'as a fso reference to a file. Variable will be managed by getFileAsFSO method.
private arrIllegalWindowsFileNameCharacters
private defaultPathSeperator
private objThisFileAttributes
Public Sub Class_Initialize
'/**
'Default constructor and initialises the file path for this instantiating object.
'The path of the file is set to the current vbscript executing directory. Hence, if your
'vbscript file was executed from c:\temp\myscript.vbs, the path
'for this class would be set to c:\temp.
'
'To Initialise your own path, see the @{link #init} constructor.
'
'@Author Jason Ely
'@version 1
'@since 1
'/
FOR_READING = 1
FOR_WRITING = 2
FOR_APPENDING = 8
arrIllegalWindowsFileNameCharacters = Array("?", "[", "]", "/", "\", "=", "+", "<", ">", ":", ";", chr(34), ",")
defaultPathSeperator = "\"
Set objFSO = CreateObject("scripting.filesystemobject")
setFilePath objFSO.GetAbsolutePathName(".")
set objThisFileAttributes = new clsFileAttributes.init(me)
End Sub
end class
VDK doc comments follow immediately after a class or procedure declaration statement and are indicated using a special opening and closing character sequence as in the below example:
public function testFunction(byref obj, byval intHairCutStyle)
'/**
'This is a VDK doc comment. Everything between '/** and '/ is considered a
'doc comment but only if this section follows after a class or procedure declaration
'statement
'
'You can format your doc comments using standard html to make them look pretty.
'VDK docs uses html 4 and above.
'
'The first part of the doc comment is always the description. After the description,
'doc comment tags follow like author, version, see, param definitions,
'returntype definitions, etc.
'
'@author Jason
'@author SourceForge
'@since VDK 1
'@returnType String
'@return returns some imaginary string to explain a doc comment
'@see www.google.com
'@deprecated this is deprecated because it will not be used in the VDK
'@param obj this imaginary function takes param obj as a parameter and gives it a hair cut
'@param intHairCutStyle specify 1 for skin-head or 2 for crew-cut
'/
'some vbscript code here
end function
VDK Doc Viewer
VDK Doc Viewer is a program that sits on top of the VDK. It extracts and displays useful information about the currently installed VDK by extracting VDK doc comments and displaying it in an easy to read html format.
With VDK Doc viewer, you can explore all the VDK libraries and find one to suite your needs instead of havig to dig through vbscript code.
You can download VDK doc viewer from the downloads section.