Are there plans format the function's comments with the same format+information as the ones in the triple quotes?
Originally posted by @HayashiEsme in 6facbfb
Yes, please do.
Originally posted by @patrick330602 in #13
With reference to a desire to format comments like so I tried to keep to the formatting of wrapping multi line comments with triple quotes as the case has been in the other functions but I ran into an interesting issue:
esme@Esme-Prestige14W:/mnt/c/Users/Esme/Developer/wslpy/wslpy$ python3 system.py
File "system.py", line 112
"""
^
SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 663-664: truncated \UXXXXXXXX escape
This isn't a feature of Python I was familiar with so I'll add some context: Python understands triple quotes that follow the start of a function as docstrings (https://www.python.org/dev/peps/pep-0257/), and expect text within it to follow 'coding styles'. In this case with code like this:
"""
Given a valid registry path, retrieves the value of an entry in the registry.
Eg: registry("HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment","OS") returns "WINDOWS_NT"
MAY return string type TODO: Doees this make sense?
A valid registry path typically includes (this this and this)
"""
The use of the double quotes and \s create issues and require escaping. The result is that documentation looks like this:
"""
Given a valid registry path, retrieves the value of an entry in the registry.
Eg: registry(\"HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment\\",\"OS\") returns \"WINDOWS_NT\"
MAY return string type TODO: Doees this make sense?
A valid registry path typically includes (this this and this)
"""
Shall we change it to #-tagged comments to avoid this issue? Is there another place you'd like the comments to be placed otherwise Patrick?
In using #-tagged it should be alright to expect that a developer can use their text editor to quickly add #s to the comments made with a shortcut like ctrl-/ in VScode