Fix Incomplete Information Given by S2 Layer Browser

[fallen_x_ashes]

Title
Fix Incomplete Information Given by S2 Layer Browser

Short, concise description of the idea
Currently the S2 Layer Browser only displays information about classes, methods, global functions, and properties if they are explcitly defined within the layer. However each layer underneath the Core Layer inherits behavior from above its heirarchy. This means that beyond the Core Layer, information shown on Layout Layers, Theme Layers, and User Layers is incomplete. This suggestion proposes fixing this by indicating inheritied properties/classes/methods as well as those properties/classes/methods explicitly defined inside the layer.

Full description of the idea
Each Layout Layer underneath the Core Layer inherits the properties, classes, and methods that are defined by the Core Layer, and this process is continued for Theme Layers and User Layers.

The Layer Browser is very useful in displaying all of the properties, classes and methods that are defined by the layer, but it only mentions classes and methods that have been explicitly defined by that particular layer. In practice, this makes the layer browser useless for anything other then the Core Layer, because for other layers, it will only show additional properties defined by that layer and global functions defined by that layer. It will not display any overriden methods the user has coded, nor will it display information on new methods the user has introduced.

At the very least, I ask that the development team to fix the layer browser to display any methods that the user may have introduced or overriden explicitly in the layer in question alone.

However, this task can be taken a logical step furthur. For any layer, a complete listing of properties/classes/methods that are available can and should be given. This will make the layer browser much more useful. At a glance an S2 programmer will know exactly what is available to them, without having to resort to switching between different browser windows that have loaded seperate layers in the layer browser, and depending on their own judgement to sort out inheritance issues.

The Layer Browser should display all information on a property/class/method, including a report on what layer originally declares it, as well as which layer ultimately overrides it (if any.) These descriptions will need to be dynamically changed in context with the layer being viewed (for example, if viewing the Core Layer, any method defined in the core layer should be reported as being defined in "this layer," but when viewing a Layout Layer, this same method will be displayed as available to the user but defined in "Core Layer".)
An ordered list of benefits

• 1) The S2 style system allows for documentation to be added to methods and classes. The Layer Browser uses these "docstrings" in the creation of its output. Currently, these docstrings are utterly useless in other layers excluding the core layer when used anywhere other then in global methods. This is a pity, for the documentation the layer browser is capable of producing can, in various circumstances, be all a beginning S2 user needs have inorder to understand the S2 system well enough to begin customizing.
• 2) Overriden methods and properties in other layers that the S2 programmer has specified will be displayed, allowing for a clear and complete presentation of the effects of all the code in the layer in question. (Presently, only properties and global functions can be shown in non-Core layers.)
• 3) Inheritance issues in the final, overall style can be laid to rest: There are many properties and methods to keep track of, and three or four possible layers an S2 programmer can use to override properties and methods defined in an earlier layer. The layer browser should be able to settle these issues of scope and present to the S2 programmer the ultimate result of the current layer loaded in the layer browser and all layers inherited before it. This should aid in the design process.
• 4) This change will hopefully make the learning curve of S2 a little less steep, make the design process much swifter and more efficent, and clear a few headaches on the part of S2 programmers.

An ordered list of problems/issues involved

• 1) The Layer Browser will almost certainly be more resource-heavy after the change then it is now. However, there is no reason why it should be any more resource itensive then simply displaying a journal, in which case the issues of inheritance and scope are resolved automatically. As the Advanced S2 Customization center is used by only a small percentage of viewers in comparison to the entirety of Livejournal, these changes should not cause any wide disruption of service despite their need for greater resources.

An organized list, or a few short paragraphs detailing suggestions for implementation

• I suggest adding two more columns to the Layer Browser. The first column will denote the first time a method/class/property was defined in which layer, and the second column will note which layer ultimately overrides it. The docstring/property value being displayed for a method/class/property will be determined by the layer that ultimately overrides it.
• The easiest way to describe this is from the top down. I do not have knowledge in how any of the internationalization layers interact with the inheritance scheme, but suspect others do. To keep the conversation simple, let us preclude the internationalization layers from the discussion.
• We will start with the User Layers. A User Layer adds the final touches on a user's style, and is auto-generated by the customization center. One may also be written by hand. Because a user may have multiple User Layers per a style, but only one may be considered "active" at a time, the question must be handled carefully. I propose that if a User Layer has not been selected for use with a Style under the "Your Styles" section of the Customization Center, that the layer browser display a message stating that the User Layer is currently "inactive". After this message, it should display a listing exactly like the current one, using only material from the layer itself, and going no furthur. However, if any methods are present in the User Layer, they should also be displayed as properties are, alongside with their respective docstrings.
• If a User Layer has been set to be used with a style, then the Layout Browser must dig a little deeper and analyze the Theme Layer that the User Layer depends upon as well. (If a Theme Layer is not present, the Layer Browser will apply the same process about to be described to the Layout Layer.) At this point it will add any properties/classes/methods that are defined in the Theme Layer to the documentation of the User Layer. If it happens to find a property/class/method declaration that, apart from value or docstring, is a complete match to the previous User Layer, then it will mark that property/class/method as having been overriden in the User Layer and initially defined in the Theme Layer.
• As you can imagine, the process continues until all layers of inheritance have been exausted and only the Core Layer remains. The Layout Browser will then analyze the Core Layer. To allow for the addition of new Core Layer versions in the future, it should analyze the Core Layer specified for use in the Layout Layer. Then, as it did with the all other layers, the Layer Browser will create the documentation for all properties/classes/methods defined in the Core Layer and add it to the previously generated documentation. If a match for a property/class/method is made to any of the previous functions defined in the Layout, Theme, or User Layers, then it will be noted as an overriden function and the location of the initial definition as well as the location of the ultimate override will be made.
• This is a top-bottom view of the what the end result should look like, but I do not in the least pretend that this is how the final algorithm will look like. There may be more efficent ways of accomplishing the above tasks.
• It should also be noted that I chose a top-bottom way of explaining things to illuminate what should happen if the S2 programmer chose to view a Layer in the middle of the inheritance heirarchy. Cleary, the Layer Browser will begin at that Layer's level and continue downward from that point only, without any regard to other layers (in this example, Theme or User Layers.)