Can we have a doc string or xml comment in AutoIt

[kcvinu]

Hi there,

Python has doc strings to comment out classes and functions

VB.NET has xml comments to do the same.

Does autoit has anything like it. Why i am asking this because, when i am working with script file which has so many functions, i need to use SciTe Jump for reading functions. But those functions which has no comment are really difficult to understand. Is there any remedy for this ?

[water]

You mean the ; character or #cs and #ce as describeded here?

[kcvinu]

Hi 

water, I mean, a special comment for what the function deos and what are the parameters. If we add a special comment to our UDF, then later when we typing the function name in SciTe, we should see a tooltip or something like that. It will sow us what this function does and what are the parameters . 

[water]

That is exactly what the link Adding UDFs to AutoIt and SciTE (already posted by melba and me) does.

[Melba23]

kcvinu,

Do you actually read the answers that you are given?

M23

[JohnOne]

 

But to make coding with these UDFs even easier you can also add CallTips and AutoComplete for them.

 

As you might expect, the full SciTE4AutoIt3 package makes it easy - have you downloaded and installed it yet? If you have then just open SciTEConfig on the Other Tools tab and press Run User Call Tip Manager. Then you just need to select the UDF file to add and everything is done for you automatically.

[kcvinu]

Hi all,

I did what you say. And i wrote a comment with #cs and #ce method. But when i start calling the same function in another script, there i can't see the comment. 

[Melba23]

kcvinu,

One last try.

Have you used the User Call Tip Manager within SciTEConfig to add the function to the relevant SciTE files? Merely adding a comment to the function script file itself does nothing at all to get calltips and autocomplete in SciTE - you need to use the Manager or add the data to the various files manually. As you have been told several times, all is explained in the Adding UDFs to AutoIt and SciTE tutorial in the Wiki.

M23

[SadBunny]

kcvinu,

One last try.

Have you used the User Call Tip Manager within SciTEConfig to add the function to the relevant SciTE files? Merely adding a comment to the function script file itself does nothing at all to get calltips and autocomplete in SciTE - you need to use the Manager or add the data to the various files manually. As you have been told several times, all is explained in the Adding UDFs to AutoIt and SciTE tutorial in the Wiki.

M23

 

I don't mean to hijack this thread, but I didn't know that was possible (never really needed it) but decided to try it too. Doesn't work for me either. Walked through the walkthrough behind that link, used the special tool, everything looked fine, but autocomplete and function help didn't work. Function itself works fine if I include my new library. Then checked all the manual steps, calltips and UserUdfs and such, all looked fine. Even after multiple restarts... Am I probably missing something simple (which may also help kcvinu) or should I start a new thread including my test code?

[Melba23]

SadBunny,

Not a hijack at all. Let me test and see what I get - as I wrote the Manager I am very interested to see the result.

M23

[SadBunny]

For completeness' sake:

; zzzuserinteract.au3

#cs
    Title: Test Title
#ce

;===============================================================================
;
; Function Name:    _mytestfunc()
; Description:      testdesc
; Parameter(s):     $msg    - testparamdesc
;
;===============================================================================
Func _mytestfunc($msg)
    msgbox(0,0,"_mytestfunc works!")
EndFunc   ;==>_mytestfunc

#include <zzzuserinctest.au3>

_mytestfunc("hi")

Works like a charm. I just don't get autocomplete or function help. I stole my library markup from Word.au3.

---

This was autogenerated by the tool after writing the above code and untouched by me:
 

au3.user.calltips.api

Func _mytestfunc($msg) test3 (Requires: #Include <zzzuserinctest.au3>)

au3.UserUdfs.properties:

au3.keywords.user.udfs=func _mytestfunc

[Melba23]

SadBunny,

Yup, already found the problem. The utility does not remove "Func " before the function name in the file - which prevents SciTE from recognising it. :blush:

I am not at all sure how that happened, but here is a modified version which does work when I test it - see if it does for you too (it is a zipped exe so I can attach it):

<snip>

If you are happy I will ask Jos to release a beta version ASAP.

M23

Edit:

kcvinu,

My apologies for the tone of my earlier post - it seems I was the one at fault. :blush:

 

Edited September 27, 2017 by Melba23
Code removed

[SadBunny]

I am not at all sure how that happened, but here is a modified version which does work when I test it - see if it does for you too (it is a zipped exe so I can attach it):

 

Took some time to test as I had two barfing AV applications and Windows Smartscreen to drag it through, but finally I got it to run. It works! Though I find the tool's GUI quite confusing and it only seems to work with direct mode (not with header mode, but as I didn't research it this may well be my misunderstanding), but at least it can get the thing to work now.

New content of au3.user.calltips.api:

_mytestfunc($msg) test4 (Requires: #Include <zzzuserinctest.au3>)
Func _mytestfunc($msg) test3 (Requires: #Include <zzzuserinctest.au3>)

This works "by accident" I guess? Maybe include a quick check to repair broken entries like this? It may well be too obscure a tool to worry about though, especially since it works like this too.

New content of au3.UserUdfs.properties:

au3.keywords.user.udfs=_mytestfunc func _mytestfunc

---

Thanks! I guess I won't be using it much as I have no trouble with keeping track of my library functions and I only ever write relatively small scripts in AU3 nowadays, but it is good to know that the functionality is in there.

Hopefully this all will help kcvinu. Though I agree that kcvinu could help others help him/her better by being somewhat more complete in his/her questions.

Edited February 24, 2015 by SadBunny

[Melba23]

SadBunny,

Great! I will pass the amended file to Jos so he can release a new Beta.

You can remove the incorrect entry from the Manager by pressing the "View Tips" button, selecting the erroneous entry in the ListView and pressing the "Delete" button.

Sorry you find the interface confusing - as I wrote it I obviously do not and you are the first to mention it. The default "Header" mode requires a formal UDF header as I put in my UDFs (and which used to be in all the AutoIt UDFs until we changed the layout during the past development period). This is the first few lines of an example header:

; #FUNCTION# =========================================================================================================
; Name...........: _CFF_Choose
; Description ...: Creates a dialog to chose single or multiple files or folders
; Syntax.........: _CFF_Choose ($sTitle, [$iW = 1, [$iH = 1, [$iX = -1, [$iY = -1, [$sRoot = "", [$s_Mask = "", [$iDisplay = 0, [$iMultiple = True, [$hParent = 0]]]]]]]]])
; Parameters ....: $sTitle      - Title of dialog - only necessary parameter!
;                  $iW, $iH     - Width, Height parameters for dialog (Default and minimum = 250 x 300).  Set negative for resizable dialog
;                  $iX, $iY     - Left, Top parameters for dialog (Default = centred)
[...]

"Header" mode looks for specific "Description" & "Syntax" lines which in your test header will not be recognised/found. So you need to use the "Direct" mode, as explained in the SciTE4AutoIt3 Help file.

M23

[SadBunny]

"Header" mode looks for specific "Description" & "Syntax" lines which in your test header will not be recognised/found. So you need to use the "Direct" mode, as explained in the SciTE4AutoIt3 Help file.

 

I dove straight in starting at that link provided in this thread and I never saw any mention of the help file. I trial&errored my way through it Maybe if you start in the helpfile it's more clear, but all I saw was this link in this topic that supposedly explained everything Well... It didn't. Anyway, there was enough information to at least find the right tool to get it to work, so good enough for me. Glad I was able to contribute.

Thanks for all of your awesome work.

[Melba23]

SadBunny,

 

all I saw was this link in this topic that supposedly explained everything Well... It didn't

Point taken. I will look at amending the Wiki tutorial later today - at least telling people to look at the SciTE Help file first.

M23

[kcvinu]

Hi 

Melba23, now everything is perfect. I can add some explanations to my UDFs. And they are visible when i writing code. This is what i wanted. Thanks a lot. I don't think your tone in previous comment needs an apology. It's my fault that i didn't express the problem correcly.

[Melba23]

kcvinu,

Glad to hear it.

M23

[kcvinu]

Hi all, 

I am requesting the authors of all UDFs to include a header or a comment for all functions. So that we can understand what the function does with a tooltip.

[Melba23]

kcvinu,

Remember that the Manager utility will fill in the function syntax automatically even if there is no header - and it prompts the user to add a suitable description for each function found if one is not present. So it is not hugely difficult to add suitable calltips yourself even if the UDF authors do not provide a "standard" header - although I agree that such headers are very useful and add them to all my UDFs.

M23