Why is documentation of official UDFs missing?

[Wiliat87]

Why do official UDFs not comply with official UDF standards?

Most of the official UDFs have this:

; #FUNCTION# ====================================================================================================================
; Author ........: randallc, Ultima
; Modified.......: Gary Frost (gafrost), Ultima, Zedna, jpm, Melba23, AZJIO, UEZ
; ===============================================================================================================================

as their documentation. Which also means, do you write the included .chm docs directly? Not by parsing the source files? Or do you just strip it out of the sources before publishing?

[Melba23]

rindeal,

We removed the headers from the standard UDFs with the last release as having 2 places where the code was documented (the function header and the Help file) meant that there was a risk of inconsistencies between them. We now have only documentation in the Help file pages, which makes the whole thing much simpler to maintain.

M23

[Wiliat87]

So does it really mean that the help files are not generated from the source files?

[Melba23]

rindeal,

And why do you need to know?

M23

[Wiliat87]

Because if you want to have it simple to mainatin why do you to put the docs somewhere else than to the source code? It's harder for you to write and for me to read.

[BrewManNH]

Maintaining the help file is much easier than maintaining the help file and the headers.

Although I understand why it was done the way it was done, I much preferred the headers as they were previously but I've learned to adapt also.

[Melba23]

rindeal,

And you are well-versed in the ease of maintenance of the AutoIt repository?

Have you yet to discover F1 in SciTE which pulls up the Help file page for the selected keyword/function/operator/etc?

There are a lot of AutoIt users out there who find the Help file the best way to access the documentation - and the AutoIt developers felt that removing the headers was the best way keep things simple and in sync (with which decision I entirely agree). So that makes a fair number who do not agree with your premise.

Sorry if we do not do things the way you would do them - which seems to be a constant feature of your posts - but our current setup allows us to release internally consistent and (for the most part) working versions of what has become a fairly complex language. How we do this is constantly under review - such as the recent decision to remove the function headers - and we welcome ideas on how we might improve. But we also reserve the right not to adopt suggestions that we believe would be detrimental to AutoIt.

M23

Edited March 16, 2014 by Melba23
Typos

[Melba23]

rindeal,

I think this sums you up quite nicely - especially after our PM exchange earlier today.

M23

[guinness]

It was me who removed them and I did it because it makes my job a whole lot easier. Not to mention it was 4MB worth of duplicate material and we all know how people love to complain about filesize.

Edited March 16, 2014 by guinness

[czardas]

I'll continue to add Headers to some of my own functions for the simple reason that I continually need to refer to complex information while I am coding and I frequently dump everything into a single file. Some functions don't need as much detail so I just use comments.

[

; Return the 1st Inversion of a binary string variant, scale modulation
Func _ModeInversion($sBin)
    Return StringRegExpReplace($sBin, "(0*1)(.*)", "$2$1")
EndFunc

;

If I had to write out full header information for every one liner, It would drive me mad. Maintenance of the bundled UDF libraries is another question altogether. I believe it's a quetion of inventing the right portable syntax, which also doesn't interfere with 3rd party software. That may or may not be complicated depending on the software specs.

[Wiliat87]

Thank you very much, @guiness, not for removing the headers, but for such a fully appropriate post.

[Wiliat87]

I'll continue to add Headers to some of my own functions for the simple reason that I continually need to refer to complex information while I am coding and I frequently dump everything into a single file. Some functions don't need as much detail so I just use comments.

[

; Return the 1st Inversion of a binary string variant, scale modulation
Func _ModeInversion($sBin)
    Return StringRegExpReplace($sBin, "(0*1)(.*)", "$2$1")
EndFunc

;

If I had to write out full header information for every one liner, It would drive me mad. Maintenance of the bundled UDF libraries is another question altogether. I believe it's a quetion of inventing the right portable syntax, which also doesn't interfere with 3rd party software. That may or may not be complicated depending on the software specs.

yes, maybe Doxygen or kind of that if you want to generat those html/pdf files, but as Melba cleared up, it's fully on the devs.

[czardas]

Doxygen does look like an interesting project. Unfortunately it doesn't support AutoIt. Reviews seem to give it a high rating though, so I'll try it.

[JLogan3o13]

rindeal,

I think this sums you up quite nicely - especially after our PM exchange earlier today.

M23

 

The word I would have chosen wouldn't have been as nice, but I agree in general. Nothing as entertaining as someone whose calls for "doing it better" simply show their ignorance

[jchd]

AutoIt is just in between the cathedral and the bazaar. Take or leave.

[Wiliat87]

Doxygen does look like an interesting project. Unfortunately it doesn't support AutoIt. Reviews seem to give it a high rating though, so I'll try it.

but is has a plugin for LUA and LUA has very similar syntax to AutoIt so I think that it could be a good place to start.

[guinness]

If you're bored you could download the source files for the documentation and then parse the text files (which we use to generate the HTML files ) to create custom headers for the functions.

[Wiliat87]

If you're bored you could download the source files for the documentation and then parse the text files (which we use to generate the HTML files ) to create custom headers for the functions.

And could you please point me to their location?

[Melba23]

rindeal,

You can find it, along with all publicly available AutoIt downloads, in the archive - you need the autoit-docs-v3.3.10.2-src.zip file.

M23

[Wiliat87]

rindeal,

You can find it, along with all publicly available AutoIt downloads, in the archive - you need the autoit-docs-v3.3.10.2-src.zip file.

M23

Thank you, and a question as always, those .txt files are output of the parser of UDF headers or were written by hand?