documentation for 'self' and 'other' keywords is not accurate to runtime behavior

[zzhamzz]

Description

Currently the most information you can get from the manual for self and other keywords is a single page:
https://manual.yoyogames.com/#t=GameMaker_Language%2FGML_Overview%2FInstance_Keywords.htm

While some of that is accurate most that deals with how those two keywords work in different scopes is inaccurate.

The most illuminating we have for self is this line:

self can also be used within [structs]- except under some specific circumstances - to reference member variables for the struct. It can also be used within constructor functions to reference the struct being generated from the constructor.

While super vague it is almost entirely untrue.

For other we have this line:

When used inside a struct declaration, other refers to the instance that is initialising the struct:

Which is not true on all cases.

The same section for other links to the manual page for Struct Constructors section Instance Variables: https://manual.yoyogames.com/GameMaker_Language/GML_Overview/Structs.htm#inst_in_struct

Which states:

Essentially, when you define a struct, all member variables on the left-hand side of the colon ":" are the struct variables, and the values and variables on the right-hand side use the scope of whatever is defining the struct (in this case, an instance).

This again is potentially incorrect in some cases.

Consider the following example:

// create event of an instance
myName = "instance";

var myStruct = {
	myName : "myStruct",
	a : self,			
	b : other,			
	c : self.myName,    
	d : other.myName	
}

with (myStruct) {
	
	myNested = {
		myName : "myNested",
		a : self,			
		b : other,		
		c : self.myName,	
		d : other.myName    
	}
}

show_debug_message("---------------------------------");
show_debug_message(myStruct.a.myName)
show_debug_message(myStruct.b.myName)
show_debug_message(myStruct.c)
show_debug_message(myStruct.d)

show_debug_message(myStruct.myNested.a.myName)
show_debug_message(myStruct.myNested.b.myName)
show_debug_message(myStruct.myNested.c)
show_debug_message(myStruct.myNested.d)

Take your time and guess what the output is. If you guess wrong or right doesn't matter. The problem is you will be guessing as there is no documented behavior that explains the output.

Either update the manual to describe current runtime behavior or update runtime behavior to match documented behavior.

My suggestion:

1. Think really hard about what the actual intended behavior is for these keywords in all cases
2. Implement it in runtime exactly as intended
3. Test it thoroughly
4. Update documentation to match intended/runtime behavior (if this ends up being a table of conditionals return to step 1)
5. Do not change the behavior without updating documentation (that is why we are here now)

Ideally these keywords will never have multiple values in the same scope. And a user will never have to 'guess' at their value.

Take your time. There are many ways to skin a cat. If these keywords remain problematic AND undocumented I'll just continue to avoid patterns that would use them. If you can document whatever their behavior truly is then they will at least be usable.

Thank you,
Your work and effort are appreciated.

This is related to closed tickets #1955 and #2020

Manual Link

https://manual.yoyogames.com/#t=GameMaker_Language%2FGML_Overview%2FInstance_Keywords.htm

[YYBartT]

Made a few first changes to the manual to clarify self and other while documenting #2783. self always refers to the "current" scope, other always refers to the scope from which you accessed the current scope (in one way or another). In events, however, without changing scope, other refers to the same thing as self.

[YYBartT]

Moved to In Progress to indicate some work has already been done for this.

[YYBartT]

Related ticket: #7274