Help File/Documentation Issues. (Discussion Only)

[TechCoder]

  Quote

 

The real question is whether a novice programmer reading HelpFile, acquires bad programming habits ?

I think that relates well to the Spanish speaking students learning English in my classes - while it is my 'responsibility' to make sure they learn 'proper' speaking habits, it is also, and a more important responsibility to expose them to a variety of words, phrases and situations where it is then THEIR responsibility to apply those to situations they face in their own lives.

There is no one way to do things, and making the help file extremely uniform, while in some ways preferable, would also eliminate the true sense of TEACHING - that there are things in this world that aren't simply answered in some manual.  

There are, in fact, some things that you must figure out for yourself!

(that is not to say there aren't some 'improvements' I'd like to see in the help file, though uniformity in coding style is not one of them)

[Mat]

I agree, which is why newly updated examples always have code inside functions, because that's what we consider to be good practice generally.

However, there is no "you must do this" rule. There is a reason AutoIt allows code at the global level, and that's so that small code snippets are much easier to read. This example would be a little bit stupid:

#include <MsgBoxConstants.au3>

_Example()

Func _Example()
    MsgBox($MB_SYSTEMMODAL, "Test", "Hello, World!")
EndFunc

I can think of no easier way to alienate a new user by giving them that as a Hello, World! example. So an element of common sense has to be applied, and like the variables prefix thread started yesterday, we can tell you "these are good programming practices" but that doesn't mean you follow them 100% of the time, you follow them unless it doesn't make sense to follow them.

[mLipok]

Thank you very much for your valuable comments.

Best regards

mLipok

[mLipok]

I do not know if this topic was not previously discussed.
But I think it's worth talking so:

In the "Keyword Reference" there is "Dim / Global / Local / Const" section.
We all probably well aware of its contents so I will not elaborate on this, the more that this is not my goal.

But I wonder if the HelpFile does not add additional information.

example provided here:

http://www.autoitscript.com/wiki/Best_coding_practices#Names_of_Variables
and
http://www.autoitscript.com/wiki/Best_coding_practices#Scopes_of_Variables

The reason because this notation is used in the UDF file.

IMHO:
Explanations as to how {create / action / description} UDF file should be included in HelpFile, as these files are part of the environment AutoIt.
Anyone who analyzes the mode of action of the UDF file, should know what to expect.
By the way, these are still good tips on how to write good code.

[mLipok]

I noticed that in some instances used alternately quotation marks, once a single character and then double quotation mark, In the same line of code.

look in

StringRegExpGUI.au3 example

$sResult &= StringFormat("%0" & $iStrLgth & "i", $c) & ' => ' & $aB[$j] & @CRLF

and

$sResult &= StringFormat("%0" & $iStrLgth & "i", $i) & ' => ' & $aA[$i] & @CRLF

What do you think about this ?

Edited May 8, 2014 by mLipok

[BrewManNH]

It's syntactially correct to use either one as long as you're consistent in their usage in opening and closing quotes. So other than a visual issue, it doesn't really matter does it?

[AZJIO]

_WinAPI_CreatePen

If the value specified by the nWidth parameter is zero

fnPenStyle

Edited May 17, 2014 by AZJIO

[mLipok]

AZJIO

I make a Track Ticket ##2724

Cheers

mLipok

[AZJIO]

IniReadSectionNames
The number returned is limited to the names of the lengths of all the names of no more than 32,767 characters.

#include <Array.au3>
$Ini = @ScriptDir & '\test.ini'
For $i = 1 To 5000
    IniWrite($Ini, (100000000000000 + $i) & 'a', 'Sec', 'var1')
Next
$a = IniReadSectionNames($Ini)
_ArrayDisplay($a)
FileDelete($Ini)

 
_IEImgGetCollection -> Example 1
to the 6th Image
4th Image Info

_IEQuit
It is therefore good practice to call _IEQuit() whenever the browser process is not needed after the script exists.
exits ???

FileCopy
Examples became difficult

Exit ; protection against accidental startup

; Please note, copying is not recursive, subdirectories are not processed.

; Copies all log-files in txt-files, leaving the original names of the same
; Flag 9 = (1 + 8) where 1 - to overwrite the file, 8 - to create the destination folder
FileCopy("C:\Temp\*.log", "C:\Temp2\*.txt", 9)

; Copies all .txt files with their original names.
; Without the flag = 8, if the destination folder does not exist, the copy will not happen
FileCopy("C:\Temp\*.txt", "C:\Temp\TxtFiles\", 8)

; Copies the file to a different folder with the specified name. Flag of 9 = (1 + 8)
FileCopy("C:\Temp\file.txt", "C:\Temp\TxtFiles\NewFile.txt", 9)

; Create a destination folder if you do not want to check for a folder using the flag = 1 for subsequent calls FileCopy.
DirCreate("C:\new\data1")
FileCopy("C:\old\file1.txt", "C:\new\")
FileCopy("C:\old\file2.txt", "C:\new\data1\")

  Quote

this flag determines whether to overwrite files if they already exist.

 
You repeat the same thing 3 times. Once in the flag name, the second time in the parameter description, the third time in a note.
 
DirCreate

  Quote

Failure: 0 if there is an error creating the directory.

If the directory already existed, whether the function should fail?
Failure: 0 if the directory does not exist after the execution of the function

_IEAttach
of of

Edited May 26, 2014 by AZJIO

[AZJIO]

FileOpen

A file may fail to open due to access rights or attributes.

A file may fail to open due to access rights or attributes (R for the flag 1, RSH for 2).

#include <File.au3>

$sPath = @ScriptDir & '\Test.txt'
_FileCreate($sPath)
MsgBox(0, 'flags', _Test($sPath))
FileDelete($sPath)

Func _Test($sPath)
    Local $hFile, $sRet, $Ret = ''
    $aAtr = StringSplit('RSHAT', '')

    For $i = 0 To 2
        $sRet &= $i & ' = '
        For $j = 1 To 5
            FileSetAttrib($sPath, '-RSHAT') 
            FileSetAttrib($sPath, '+' & $aAtr[$j]) 
            $hFile = FileOpen($sPath, $i)
            If $hFile = -1 Then $sRet &= FileGetAttrib($sPath) 
            FileClose($hFile)
        Next
        $sRet &= @CRLF 
    Next
    Return $sRet
EndFunc

FileCopy, FileMove, FileDelete
It is possible to specify that works not recursively.

 

FileFindFirstFile
Returns a search "handle" according to file search string.

1. Initializes a search handle, defined by a path and file mask.
2. Creates an object to start searching, storing path, mask and position for the next file.

FileFindNextFile

Returns a filename according to a previous call to FileFindFirstFile.
Returns the next filename defined by the search handle.

 

AutoIt -> Using AutoIt -> Running under Windows 64-bit Edition
Running the 32-bit version of AutoIt on a x64 System
The table also indicates a 64-bit AutoIt

Directories | 32-bit Value | 64-bit Value
Directories | 32-bit version of AutoIt | 64-bit version of AutoIt

Edited May 29, 2014 by AZJIO

[UEZ]

Found two wrong entries in _GDIPlus_ImageGetHeight and _GDIPlus_ImageGetWidth examples:

ShellExecute(@MyDocumentsDir & "GDIPlus_Image.jpg") must be  ShellExecute(@MyDocumentsDir & "GDIPlus_Image.bmp")

Br,

UEZ

[Melba23]

UEZ,

Fixed.

M23

[guinness]

AZJIO,

I have fixed some of the issues reported, but because you didn't create a ticket I am unable to report which ones I rejected.

[mLipok]

I have a proposal to the 

http://www.autoitscript.com/autoit3/docs/history.htm

and

"THIS IS A SCRIPT BREAKING CHANGE" description.

 

can you bold this

or even colored red ?

[guinness]

I have changed the build script to make that sentence bold (strong).

[mLipok]

Thank you.

[JScript]

Any chance we have an example of using this function:

_WinAPI_CopyRect() ; Description....: Copies the coordinates of one rectangle to another.

JS

[Melba23]

JScript,

Perhaps you could supply one for us?

M23

[JohnOne]

It's not complicated.

#include <WinAPIGdi.au3> ; for $tagRECT

$MyRect = DllStructCreate($tagRECT)

;Fill rect

$MyRectCopy = _WinAPI_CopyRect($MyRect)

[AZJIO]

AutoIt -> Using AutoIt -> Intended Use

This should be the first item in the section