Jump to content

Sky Slate Blueberry Blackcurrant Watermelon Strawberry Orange Banana Apple Emerald Chocolate
Photo

[docs] AutoHotkey_L documentation rewriting project?


  • Please log in to reply
66 replies to this topic
fragman
  • Members
  • 1591 posts
  • Last active: Nov 12 2012 08:51 PM
  • Joined: 13 Oct 2009

It's actually not that bad, however it gets complicated by some bit shifting operations which may be hard to understand for beginners. It basically shows how to implement properties that don't exist as keys in the object. In this example it gives you access to the separate color channels R,G,B as if they were defined as keys in the class.


Maybe not for you, but it was hard to understand for me. We are already trying to learn something technical, so does it make sense to use a technical example? I don't imagine many newbies to understand it, unless that is not the goal, and you guys are trying to introduce AHK_L syntax to professional coders instead. (In contrast, my father was able to get it right away, but he is a programmer with over 20 years in C++)

Think of examples from the Head First series, they seem to have an idea on how to break down coding for newbies and beginning coders. If it is our goal to teach people, this is not the way to go about doing it. My theory on learning is that if you can make it as simple as can be without sacrificing core points, that is the stroke of genius.

That's the point, meta functions are an advanced concept. You won't be able to get/understand them before you have a good knowledge of objects or classes. I also didn't say that it couldn't be improved, what I meant was that it is a relatively direct example without much other code that can distract (apart from the bit-shifting stuff as I said before).

plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011
@sinkfaze

I like that, but we shouldn't leave out intermediate users either. I agree that complete beginners need more practical examples, and tutorials as well. Maybe because I was learning about objects/classes in C# at the time that I got into the more OO parts of AHK_L in depth, but we can create interesting, fun examples for novices to utilize such concepts; including classes, meta-functions, etc.

plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

That's the point, meta functions are an advanced concept. You won't be able to get/understand them before you have a good knowledge of objects or classes. I also didn't say that it couldn't be improved, what I meant was that it is a relatively direct example without much other code that can distract (apart from the bit-shifting stuff as I said before).


Yeah, okay, they are an advanced concept. But they are highly useful as well. At the time, I understood the concept of how objects and classes work. I also understood how some of the meta-functions worked as well. I just couldn't make enough sense of the example to get a feel for the syntax, or implement it into my own code.

Funnily enough, I had very little issue grasping the concept of classes, objects, etc. from the Head First books, which are famous for the examples they use. I don't think I would have learned OOP from the current documentation.

Again, I think the question here is the teaching method, not necessarily the concept's difficulty. We are already dealing with very technical concepts, why do we have to worry about RGB and such? Is it impossible to come up with an easier to understand example that makes use of the meta-functions?

jethrow
  • Moderators
  • 2854 posts
  • Last active: May 17 2017 01:57 AM
  • Joined: 24 May 2009
Meta-Function Example:



plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011
@jethrow

Thanks for the effort :)

That is definitely a step in the right direction. It's not easy to get at first glance, but if I follow the documentation, I can now clearly see how and when each of those meta-functions will be called upon. +1

Frankie
  • Members
  • 2930 posts
  • Last active: Feb 05 2015 02:49 PM
  • Joined: 02 Nov 2008
It's a rough sketch, but what about something like this? It shows under what circumstances a function would be called. When looking at someone else's code, or a tutorial, or example, or whatever; you could refer to this, to see why they put certain code in a certain meta-function. When writing your own code, you can say, "How do I get code to run when someone does _____ with my object?" - and have an answer.
aboutscriptappsscripts
Request Video Tutorials Here or View Current Tutorials on YouTube
Any code ⇈ above ⇈ requires AutoHotkey_L to run

plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

It's a rough sketch, but what about something like this? It shows under what circumstances a function would be called. When looking at someone else's code, or a tutorial, or example, or whatever; you could refer to this, to see why they put certain code in a certain meta-function. When writing your own code, you can say, "How do I get code to run when someone does _____ with my object?" - and have an answer.


That definitely looks great as well, I like the fact that we can hover over exact code to tell what it does or give more details. But when jethrow's code is executed, you can actually follow along with the program, and see where each step goes. A combination of the two approaches would appear ideal.

nimda
  • Members
  • 4368 posts
  • Last active: Aug 09 2015 02:36 AM
  • Joined: 26 Dec 2010
Green-on-black = unreadable :p

sinkfaze
  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008
That's not really a helpful example of meta-functions for a beginner. Don't get me wrong, the simplicity of the demonstration is nice, but a simple demonstration doesn't mean anything if someone doesn't know why they should use it. There needs to be a simple example with an appealing purpose.

jethrow
  • Moderators
  • 2854 posts
  • Last active: May 17 2017 01:57 AM
  • Joined: 24 May 2009

That's not really a helpful example of meta-functions for a beginner ... why they should use it.

I would cover:
1. Arrays in general. This would include Associative Arrays, and touch on how Arrays are an object.
2. Arrays & their usage in AHK(_L)
3. Customizing Arrays/Creating Custom objects (advanced training)

Sure - but I'd counter with: Meta-Functions/Custom Objects aren't a beginner topic. IMO, there should be an interactive tutorial that covers the basic though process behind custom objects - AHK OOP if you will. (Note: I don't like referring to AHK_L as OOP)

Also, that was just an example of each of the Meta-Functions. I'm all about creating some top-notch documentation &/or training - however, if we are going to, I think we need to layout an outline of what all we want to cover, how we want to cover it, and work as a team to develop it. From what I've seen, Frankie is pretty good at developing interactive webpages. I have lots more ideas, but how far do we want to take this before we get a definite gameplan/roadmap from poly? Or do we just move forward with AutoHotkey_L regardless?

sinkfaze
  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008

Meta-Functions/Custom Objects aren't a beginner topic.


Of course we're in agreement on that and on the priority scale:

I don't think that classes are really something the documentation needs to focus on gearing to the beginner anyway. It could obviously use some revision but I think it should be much lower priority compared to demonstrating simple ways objects/arrays can be used that are pertinent to things beginners might do.


I assumed that because continuation of the discussion on meta-functions persisted afterwards that the attempts to simplify were nonetheless being made. Apologies if I didn't see it properly.

...how far do we want to take this before we get a definite gameplan/roadmap from poly? Or do we just move forward with AutoHotkey_L regardless?


Not much point in waiting if the problem already exists.

plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

That's not really a helpful example of meta-functions for a beginner. Don't get me wrong, the simplicity of the demonstration is nice, but a simple demonstration doesn't mean anything if someone doesn't know why they should use it. There needs to be a simple example with an appealing purpose.


You make a good point, but it is much better than the original example by leaps and bounds. It actually shows you how each function is called and works during execution; that is good enough to arm any solid intermediate.

For beginners, I agree that the example must imitate a real-world one, which is difficult, but not impossible to do. We can create a problem that meta-functions can take care of quite well, and detail its processes carefully. If you see my use of meta-functions in my thread, for example, I used the new meta-function to create support tickets which would have all the necessary default data that each support ticket needed. I reasoned that the New meta-function would prevent me from creating a separate method and calling it each time when each of my objects had to start off with the same routine of filling out the ticket with data.

I'm sure you guys have used the meta-functions in your scripts to simplify the code, right? Maybe we can start with those.

plastikglass
  • Members
  • 93 posts
  • Last active: Apr 26 2013 01:59 PM
  • Joined: 24 Aug 2011

Meta-Functions/Custom Objects aren't a beginner topic.


Of course we're in agreement on that and on the priority scale:

I don't think that classes are really something the documentation needs to focus on gearing to the beginner anyway. It could obviously use some revision but I think it should be much lower priority compared to demonstrating simple ways objects/arrays can be used that are pertinent to things beginners might do.


I assumed that because continuation of the discussion on meta-functions persisted afterwards that the attempts to simplify were nonetheless being made. Apologies if I didn't see it properly.



When I read the thread, it asked for newbie input in regards to objects and its associated features. I did not have too much trouble with objects in AHK_L, but I got stuck with the meta-functions; that is why I asked about those right away.

The reason I got into objects in AHK_L is because I was interested in converting my procedural program into an OOP. Maybe if we can show some before and after scenarios where we convert traditional programs into OO ones, we can show beginners why they should take a look at objects.

jethrow
  • Moderators
  • 2854 posts
  • Last active: May 17 2017 01:57 AM
  • Joined: 24 May 2009

... we can show beginners why they should take a look at objects.

Should they? Arrays, sure - but IMO general objects (customized ones for sure) don't need to be promoted in the documentation or community. They are there if you want to use them - particularly for developing class libraries/modules - but the documentation should be focused on AHK as a procedural language/tool, IMO.

That's not to say, however, that we shouldn't have the best documentation/tutorial out there on the thought process behind & usage of objects ...

sinkfaze
  • Moderators
  • 6367 posts
  • Last active: Nov 30 2018 08:50 PM
  • Joined: 18 Mar 2008
Perhaps something like this would help explain the purpose of the __New meta-function on more simple terms?

series :=	new Average(13,18,13,14,13,16,14,21,13)
For type, value in series
	MsgBox, , Average - %type%, %type%: %value%
return

class	Average {	[color=#40BF00]; input value must be a comma-delimited series of numbers[/color]
	__New(p*) {
		this.Mean :=	0
		[color=#40BF00]; determine the mean for the series[/color]
		For i, n in p
			t .=	(!t ? "" : ",") n
		Sort, t, N D`,
		list :=	t, p :=	[]
		Loop, parse, t, `,
		{
			p.Insert(A_LoopField)
			this.Mean +=	A_LoopField
		}
		this.Mean :=	Round(this.Mean / p.MaxIndex(),3)
		[color=#40BF00]; determine the median for the series[/color]
		n :=	Round((Mod(p.MaxIndex(),2) ? p.MaxIndex() + 1 : p.MaxIndex()) / 2), this.Median :=	p[n]
		[color=#40BF00]; determine the mode for the series[/color]
		Sort, t, U
		Loop, parse, t, `,
		{
			RegExReplace(list,"\b" A_LoopField "\b","$0",c)
			if	!current || c > current
				this.Mode :=	A_LoopField, current :=	c
		}
		[color=#40BF00]; determine the range for the series[/color]
		this.Range :=	p[p.MaxIndex()] - p[1]
	}
}