The script should only contain a minimun set of descriptions. No one should look in a may be big source file to find out about any functions parameter information. That is not good practice to me.
A short time ago, I was developing a script to read special comment tags, don`t know what other to call. It`s like in html or xml. Here a example:
Code:
;?meta version="1.0"
;?meta requiredOsType="WIN32_NT"
;?meta source="http://www.autohotkey.net/~tuncay/this.ahk"
;?meta doc="http://www.autohotkey.net/~tuncay/this.html"
;?doc nextblock="history"
/*
v1.0
- initial release
*/
;?oc #NoEnv
Var = 10
Add(Var)
;?doc function="Add" description="Adds simply a
;? value to the variable."
Add(ByRef Arg1, Arg2 = 1)
{
Arg1 += Arg2 ;?alt Arg1 := Arg1 + Arg2
}
A ";?" statement without any tag will be merged with above one. ";?oc" is indicating, that the line is out-commented. ";?alt" stands for alternative line.
The concept is that the tag (for example here "meta" and "doc") are just standardized on another documentation. (like the w3c does) This would us allow to create more tags.
I wanted propose this, but currenty I am not sure. May be its a bit too complicated in practice.
Initially, I wanted scripts (not libraries only), that are searchible on tags we gave them, like keywords or some other properties like if the script is a library or not.
I was experimenting in developing, but gave it up. Its an uncomplete script at very early phase and does not work fully.
Code:
cmlFile := cml_openFile("cml_old.ahk")
;node := cml_getNodeByIndex(cmlFile, 1)
;msgbox % cml_getNodeName(node)
msgbox % cml_getElementByTagName(cmlFile, "doc")
;MsgBox % cml_getMetaContentByName(cmlFile, "type")
Return
cml_openFile(pFile)
{
FileRead, File, %pFile%
Return File
}
cml_getMetaContentByName(ByRef pFile, pMetaName)
{
Index = 1
Loop, 99
{
Element := cml_getElementByTagName(pFile, "meta[" . A_Index . "]")
Pos := InStr(Element, "name=""" . pMetaName . """")
If Pos
{
Pos := InStr(Element, "content=""")
MetaContent := SubStr(Element, Pos + 9)
StringTrimRight, MetaContent, MetaContent, 1
Break
}
}
Return MetaContent
}
;?section Core Functions
cml_getNodeByIndex(ByRef pFile, pIndex = 1)
{
TagIndex = 0
ErrorLevel = 0
Loop, Parse, pFile,`n,`r
{
PosStart := InStr(A_LoopField, ";?")
If PosStart
{
PosEnd := InStr(A_LoopField, A_Space, False, PosStart)
If PosEnd
{
If SubStr(A_LoopField, PosStart + 1, PosEnd - PosStart - 1)
{
TagIndex++
If (TagIndex = pIndex)
{
Node := SubStr(A_LoopField, PosStart + 1)
ErrorLevel = %A_Index%
Break
}
}
}
}
}
Return Node
}
cml_getNodeName(pNode)
{
pNode = %pNode%
PosStart = 1
If (SubStr(pNode, 1, 1) = "?")
PosStart++
Return SubStr(pNode, PosStart, InStr(pNode, A_Space) - 2)
}
cml_getNodeValue(pNode)
{
Return SubStr(pNode, InStr(pNode, A_Space) + 1)
}
cml_getElementByTagName(ByRef pFile, pTagName)
{
ErrorLevel = 0
If Not InStr(pTagName, "[")
pTagName = %pTagName%[1]
TagName := SubStr(pTagName, 1, InStr(pTagName, "[") - 1)
TagIndex := SubStr(pTagName, InStr(pTagName, "[") + 1, InStr(pTagName, "]") - InStr(pTagName, "[") - 1)
Loop, Parse, pFile,`n,`r
{
PosStart := InStr(A_LoopField, ";?")
If PosStart
{
PosEnd := InStr(A_LoopField, A_Space, False, PosStart)
If PosEnd
{
CurrentTagName := SubStr(A_LoopField, PosStart + 1, PosEnd - PosStart - 1)
If CurrentTagName = ?%TagName%
{
If Not %CurrentTagName%TagIndex
%CurrentTagName%TagIndex = 0
%CurrentTagName%TagIndex++
If (%CurrentTagName%TagIndex = TagIndex)
{
Element := SubStr(A_LoopField, PosEnd + 1)
ErrorLevel = %A_Index%
Break
}
}
}
}
}
Return Element
}
cml_getAttributeByElement(ByRef pElement, pAttribute)
{
}
Login
Register
FAQ
Search
. Poll results might be interesting though since many people seem to like the idea of documentation being part of the code...
. It is a good idea, but probably beyond my abilities.