Settings documentation highly lacking

[Brian-at-Baebies]

Affected path: extensions/api-documentation.md

Issue: There is no useful documentation for the XxxxSettings classes. These critical questions are not answered by the docs:

• What are all the possible constructor arguments?
  • e.g. the label= argument is demonstrated in examples but not documented
  • How do you specify a default value?
• How do you access the value?
  • Per example code, it appears you can implicitly coerce the object to its value (comparison operators) but this is not documented anywhere

[Brian-at-Baebies]

So, after reading code, I understand how the settings mechanism works a lot better.

The Settings objects written in the HighLevelAnalyzer subclass are class (static) variables. At instantiation, the __new__ method for HighLevelAnalyzer uses reflection (inspect in Python-speak) to enumerate all class variables, and for each it finds that is a subclass of Settings, it then adds an attribute by the same name which holds the value to the newly-created HighLevelAnalyzer object:

    def __new__(cls, settings, *args, **kwargs):
        obj = super(HighLevelAnalyzer, cls).__new__(cls, *args, **kwargs)

        for setting in cls._get_settings(): 
            name = setting.name
            if name not in settings:
                    raise ValidationError('Missing setting: ' + name)
            setting.validate(settings[name])
            setattr(obj, name, settings[name])

        return obj

(cls._get_settings() calls the inspect functions and returns a list of all class objects that are derived from Settings)

So when the Analyzer's code does, e.g., if self.my_setting == 3:, it's examining the attribute added in the constructor, not the static class variable.

I think some better-worded explanation of this whole scheme would be useful for folks that aren't content to just follow examples and really want to understand what's going on. The fact that an attribute magically appears with the same name as the class variable is, to me at least, fairly misleading in terms of understanding the mechanism.

I might come back and take a stab at writing it if I ever manage that much free time...