Add 'Signals, concise example' documentation page #9460
Conversation
manujarvinen
changed the title
AThousandShips
added
content:new page
|
Marked this 'ready for review'. Oh, and also removed some unnecessary text to make the example even more concise. This kind of page would really have helped me some time ago in my learning of GDScript and Signals. Hoping for comments before I learn some C# to update the code examples for that language also. |
|
If you want a concise example, I think it would be better to improve the Signal class reference page and link it at the top of the existing documentation. |
|
I added the shak2's suggestions to my proposal, I hope they don't mind. But I desperately need help with the CSharp portion of this proposal. I tried to add something but I don't understand it. Also, in the image there's the red arrow which is me asking if this page is put to correct spot? Other than these, in my opinion this is ready to be merged. What do you think? Here you can download the Godot Scene in order to implement and test out your CSharp code (this is only GDScript now): |
| .. _doc_signals_concise_example: | ||
|
|
||
| Signals, concise example | ||
| ======================== |
There was a problem hiding this comment.
While concise this section is far too bare, this won't help anyone unless they know some basics, it needs some slightly less minimal descriptions, and it just repeats the same as below in simplified form, which I'd say is just redundant
But I agree with Calinou and this should just link to the signal class docs,
There was a problem hiding this comment.
I'm open to suggestions, but please let's not bloat this up. In my opinion too many words is bad design and certainly won't help anyone, either. In my mind PHP language's manual pages are superior to Godot's because of their concise examples: https://www.php.net/manual/en/function.array - That could serve as inspiration (but not as strict guide, of course)
| ``SIGNALNAME.emit(arg1, arg2, ...)`` | ||
|
|
||
|
|
||
| Connect Signal (in receiver): |
There was a problem hiding this comment.
Nitpick but since this is meant to be a general and minimum explanation this adds an assumption that would harm use, by implying that the signal must be connected in the receiver
If we are making an example for the absolute beginner this would make them think the signal must be connected in some class Foo, and couldn't be connected to Foo in some Bar
There was a problem hiding this comment.
I'm still new to Godot and Signals. That's why I needed this concise clarification. Yes, let's work together to open a little bit more how the developer can utilize signals, but again, being very careful of not adding too long sentences and wording. Even too many examples can be detrimental for understanding.
|
I fixed some code and added a new description, but I'm starting to hate how this is already getting too bloated. Not much more should be added to this concise example. I would love to get this merged soon to get over it. Please comment a lot, criticize, point out flaws. Also, still, the C# code portion is needed :/ Or hey, can I just remove the C# sections? Aren't signals GDScript's unique feature? Here's how this looks like now: |
There was a problem hiding this comment.
I'm only reviewing the C# code.
Overall I'm not sure how useful this page is, considering we already have multiple documentation pages for signals.
Specifically the C# signals documentation page covers the same thing and goes into a bit more detail about C#-specific behavior (such as the difference between using Connect and the C# event to connect to signals).
The GDScript basics documentation page also has a signals section. But it looks like GDScript doesn't have a dedicated page for signals.
And then there's the Using signals tutorial which goes in depth on how to use signals, as well as the Signal class reference which has a simple example about declaring signals.
|
Okay, things are quite polished now. |
|
Is it really this hard? Should I manually go through every single commit? Can I just remove this Pull Request and make a new one with some fresh simple small files that are changed/created and nothing else? |
manujarvinen
force-pushed
the
master
branch
2 times, most recently
from
dc90d80
to
2041600
Compare
- Added a new `signals_concise_example.rst` page - Included GDScript and CSharp code examples - Updated the `index.rst` to include the new example in the toctree. - Added and updated related images for clarity. - Made several typo fixes and text reformatting for better readability. - Tested CSharp code in a Godot project to ensure it works correctly. Co-Authored-By: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com> Co-Authored-By: Raul Santos <raulsntos@gmail.com>
|
Okay, pheww. Finally squashed the whole thing into one commit. What a mess at first but I think I got hang of it. Not easy gitting, I must say. So, what's the next step? |
|
Now would be a great time to merge this PR since the 4.3 got released, what do you think? This is ready to go. Imo, worthy addition - I've grown to love Signals nowadays, after understanding them from a simple example like this. |
|
@AThousandShips @Calinou I'd be pleased to know what to do about this now? Should this go through some tough review still? Thank you for your time :) |
Hi,
First time documentation updater here.
I'm aware of the Content Guidelines.
This concise Signal example is as short as it possibly can. Unlike the other Signal examples. I for myself tried for almost a month to get Signals to work by reading the manual but simply couldn't understand the Signal mechanics no matter how precisely I read the manual.
So I made this tutorial first and foremost for me to wrap my head around Signals.
I finally undestand them!
Image-version of this documentation page of mine:
https://images.manujarvinen.com/signals_concise_example.jpg
This example of mine tells all the essentials and nothing more. Really hoping it would get included.
I'll add the C# code portions if you think this is a good idea.