Good day, Problem: the way signals are implemented. To get you caught up: there is a generic signals mechanism (good) that is used all over the C and lua code. Various bits of the code randomly emit signals by entering just the string name. It so happens that the properties are consistently named and relatively intuitive, but: - Typos happen. If they do, there is no way to catch them, since any string is a valid property. - Properties are just whimsically named in-place. As such, there is no way to automatically generate documentation for them for luadoc (and there is none!). It so happens that profjim was extremely kind enough to look through all the source and find all of the property names and arguments and put them on the wiki. However, this is clearly a poor solution. If a single signal is added and the wiki is not updated, finding / noticing it afterwards is very hard. - Properties happen to be named consistently, but it's simply because a single person wrote them all. In the long term, unless careful care is taken, inconsistencies may arise. - In general, it's very bad programming practise to use "magic values". This is error prone, poor for documentation, and in general gives me the creeps :)
Proposed solution: Make a database of signals. Perhaps someone has a better idea than this, but here's mine. We create a set of nested tables in awful. This is pretty much just a large collection of globals. They would be named like: awful.signal.client.prop.border. Each of these variables would have a string associated that is the property string currently used. Ex. awful.signal.prop.border = "property::border". Then: - When code wants to emit or catch a signal inside awful or the C side, it can access these variables. (C side can read awful lib variables, right?) - We document the variables using the standard luadoc stuff and get rid of the wiki Signals page. - We reduce the chance of typos. - We increase consistency of the variable names because they're all defined in one place. Thoughts? Improvements? People willing to implement this? Cheers, -AT -- To unsubscribe, send mail to [email protected].
