Documentation for Signals?

[notFoxils]

I was wondering if there is documentation for the various signals called during SomeWM's lifetime.

For example in the Client Rules documentation there is an example that shows we can listen for the request::rules.

I'm not sure if this is an AwesomeWM inherited thing, in which I cannot seem docs for it, where I was searching for a Signals section in the docs (client class as an example, ruled.client is missing the section).

On the other end if this is a SomeWM thing then the documentation seems to be lacking in this case.

Obviously I was able to find this one in SomeWM's docs, but not really in a immediately obvious place and still lacking a formal documentation.
Something like:

Signal abc is used for xyz

or

Signal abc happens after xyz and because of 123.
Make sure not to frobnicate foobars in the callback as it may not be ready yet.

[notFoxils]

I'm down to help out if this is something that doesn't exist, although I lack experience in C and with AwesomeWM's API in general at the moment, so I'll have to get a little bit familiar before I can start understanding and searching through the code.
(SomeWM has been my excuse to make an actual config)

I love this project and thanks to the all the developers/contributors who make it happen.
(Hopefully I can add to the effort!)

[unai-ndz]

Most of the signals are indeed inherited from awesome.

Awesome lists signals inside each component's page. i.e. https://awesomewm.org/apidoc/core_components/client.html#Signals

Somewm has them here: https://somewm.org/docs/reference/signals

And here if you use the latest git from the dev branch:
https://somewm.org/docs/next/reference/signals

The somewm docs have changed recently.
Before it didn't list all the signals but it looks like now it does.

[notFoxils]

To address the resources you had mentioned:
Your link to AwesomeWM's docs is another example of those Signals sections I was looking for.

I briefly remember seeing SomeWM's Signal Reference reference page, and somehow forgot about it.
This does bring up another point, those pages are actually missing the request::rules signal mentioned by Client Rules example that I had posted about.

I did some research after making this post and double checked that request::rules doesn't show up inside AwesomeWM's docs.

Now this is just for this signal, there could be more missing, but I haven't looked for/encountered any others.

Now to bring insight for the signal I was looking for:
It seems that the request::rules signal originates from the initial commit to this repo.
It's called using a callback to AwesomeWM's client-(module?, file?, class?, let me know the terminology)'s scanning signal, see the code, and the scanning signal docs.

And a final point:
I'm starting to feel as if having to look in two different places to piece together how things work is pretty inconvenient.
I think SomeWM's API & documentation should specifically acknowledge itself as a compatible superset of AwesomeWM's API & documentation and then absorb it.

[notFoxils]

I guess I forgot to clarify what my reply was for.
Its more for answering the secondary hidden question in what does request::rules do, and then also creating some talking points for how the documentation should be done.

In this case its probably better to continue my conversation as another discussion.

[unai-ndz]

I forgot about that one. Yeah, a few things are missing in the awesome docs or just documented as examples like that one signal.

But it looks like @JimmyCozza has already started documenting at least the signals in parallel with awesome so it seems appropriate to open an issue requesting docs for request::rules in this repo.

As for your other point. I don't wanna put words in his mouth but taking into account the roadmap for 2.0 it will possibly get it's own complete docs eventually as there are lots of additions and changes planned.

[JimmyCozza]

Yeah I do have aspirations to get the docs really fleshed out more fully. When I started the docs, I was not really convinced this approach was a good one (and I'm still not) but I figured some docs were better than wasting time trying to find the perfect documentation solution. So I just went with this docusaurus approach and decided that signals were a whole lot of stuff that I hadn't planned on changing, so I intended to just point to the awesomewm docs for signals for the time being...

However, that certainly needs to change, most of all for 2.0 since I have reworked some of the internals of signals...

I'll try to get something more comprehensive sketched up that helps really flesh out the documentation for signals. Stay tuned.

[JimmyCozza]

I added a bit more last night/this morning that hopefully clarifies and enumerates the signals a bit better.

I was relying probably too much on signal references in the awesome docs, read through the updated docs and lmk how it looks.

Also with regards to 2.0, I made some serious structural changes to how signals work recently so I added context around the new queue model for signals too. Hopefully that's more clear now.

[notFoxils]

Great improvement!

The changes to the Signals Reference page really alleviates the point that I had made earlier.

I'm starting to feel as if having to look in two different places to piece together how things work is pretty inconvenient.
I think SomeWM's API & documentation should specifically acknowledge itself as a compatible superset of AwesomeWM's API & documentation and then absorb it.

On top of that, the addition of the Concepts/Signals page is very informative and helps a lot in figuring out the "correct" way of doing things.
More specifically for me ordering and handler-safety sections clear up a lot in how things are going on that the architecture page originally hadn't.