Sorry for taking a bit to get back on this, but I'm still mulling
over this. Generally, this looks good. Here are some additional
- The explanatory text is very helpful when writing a script,
however we should make it clear that once a script is done, this
should be removed, as otherwise we'll end up with many scripts
having the same boilerplate in them. So, perhaps it makes sense to
start anything that's just explaining something with an explicit
# REMOVE-ME: The export section contains the external ...
# REMOVE-ME: ......
- Also, some elements have a documentation string (i.e., something
that will end up in the auto-generated documentation later) while
others don't. I think that generally at least everything in the
export section should have documentation.
- Taking the two previous points together, it doesn't yet become
clear what is documentation for a script's *users*, vs. what is help
for a script *writer*.
- As an alternative, we could keep the writer help inside a script
to a minimum, but have an additional external document giving more
details. Not sure which approach is better.
- The Notice enums should be documented as well.
- Another thought, considering our goal of building "configuration
wizards": it would be cool if the such a wizard could extract from
the script everything that it needs for providing the user with a
corresponding configuration dialog. Actually I don't think there's
much additional stuff needed to facilitate that once the
documentation strings are in place, but it's worth thinking about
what else could be helpful here.