Update subst docstrings and minor formatting #4784
Conversation
This is a no-code change (1) - addition or modification of docstrings, adding blank lines for readability, fixing spacing between code and comment, and a few typing annotations. 1. there are a few instances of else dropped or elif turned to if when the previous block ended with return or raise. Those are *technically* code changes, but have no behavioral effect. Signed-off-by: Mats Wichmann <[email protected]>
SCons/Subst.py
Outdated
| A substitution mini-language describes how SCons performs token | ||
| replacement on strings or lists of strings that are intended for use | ||
| in commands. ``${expression}`` is the primary format. ``expression`` can |
There was a problem hiding this comment.
not strictly true. in most cases $VARIABLE is the preferred version. ${VARIABLE} causes more complicated processing to happen.
There was a problem hiding this comment.
I didn't mean preferred, just that it's the baseline - everything works with {}, only some things can omit it. I'll see if there's another way to word that.
There was a problem hiding this comment.
I'd say $ENVVAR is the primary format if you can't use that due to strings following it or because you have an expression you want it to evaluate, otherwise use ${expression} ?
There was a problem hiding this comment.
I'd say
$ENVVARis the primary format if you can't use that due to strings following it or because you have an expression you want it to evaluate, otherwise use${expression}?
I'd be more inclined to keep wordsmithing this if it was for the manpage (something I think we've done already). Just wanted to have a block in the module that said something about the overall purpose.
There was a problem hiding this comment.
I don't think we should have ${expression} as the primary format. There're performance implications on that form vs $ENVVAR
Signed-off-by: Mats Wichmann <[email protected]>
|
I can invert it. |
That'd resolve my concerns. Thanks! |
Didn't seem to flow actually "inverted", but a new edit coming through. |
Signed-off-by: Mats Wichmann <[email protected]>
mwichmann
force-pushed
the
maint/subst-docstrings
branch
from
7091d82 to
9352481
Compare
Two string containers defined here, Literal and SepcialAttrWrapper, do not subclass UserString. Add a note on that for uses which might expect them to be identifiable as string types. CmdStringHolder does subclass UserString, so it doesn't have this caveat. Signed-off-by: Mats Wichmann <[email protected]>
2 participants
This is a no-code change (1) - addition or modification of docstrings, adding blank lines for readability, fixing spacing between code and comment, and a few typing annotations.
elsedropped orelifturned toifwhen the previous block ended withreturnorraise. Those are technically code changes, but have no behavioral effect.