missing docstrings (which power .help and .command)

[ineeee]

docstrings are used in decorated functions (i.e. @hook.command) to show help in the chat when people use the command incorrectly. there are a lot of missing docstrings currently, which makes commands silently fail (or sometimes throw an exception) when they don't get the expected input.

i'm currently working with adrift to get docstrings to every single command.

the docstrings in taigabot should follow pep-0257: one-line docstrings using triple quotes as a string delimiter.

this code will check for missing docstrings:

https://github.com/inexist3nce/Taigabot/blob/146fa7b6b2fabc05f033593c72007c822e56b074/plugins/core_tests.py#L4-L11

edit

validated using:

.test_docstrings
flake8 --ignore=E,W,M,Q --docstring-quotes=double --select=Q002 .
^([a-z0-9]+)( <[0-9a-z #@|]+>| \[[0-9a-z #@|]+\])*( -- |: )(.+)$

[ineeee]

progress

outdated, see next comment

`.test_docstrings` output

``` 14:05:50 #chan .test_docstrings commands that failed the docstring test: - missing: britbong defined in plugins/4chan.py:178 - missing: smiley defined in plugins/datafiles.py:77 - multiline: 8ball defined in plugins/datafiles.py:96 - missing: furry defined in plugins/furry.py:44 - missing: e621 defined in plugins/furry.py:44 - missing: mlb defined in plugins/major_league_baseball.py:37 - missing: marketing defined in plugins/marketing.py:8 - missing: bank defined in plugins/bank.py:70 - missing: bene defined in plugins/bank.py:143 - missing: heartbleed defined in plugins/heartbleed.py:258 - missing: host defined in plugins/core_ctcp.py:154 - missing: fhost defined in plugins/core_ctcp.py:176 - missing: trolltest defined in plugins/core_ctcp.py:183 - missing: rainbow defined in plugins/utility.py:167 - missing: gay defined in plugins/utility.py:167 - missing: gaycow defined in plugins/utility.py:173 - missing: wrainbow defined in plugins/utility.py:186 - missing: usa defined in plugins/utility.py:198 - missing: uk defined in plugins/utility.py:198 - missing: radio defined in plugins/radio.py:33 - missing: aradio defined in plugins/radio.py:75 - multiline: part defined in plugins/core_admin_global.py:230 - multiline: cycle defined in plugins/core_admin_global.py:255 - multiline: say defined in plugins/core_admin_global.py:288 - multiline: me defined in plugins/core_admin_global.py:312 - multiline: act defined in plugins/core_admin_global.py:312 - missing: cryptocoin defined in plugins/coins.py:45 - missing: cg defined in plugins/coins.py:45 - missing: btc defined in plugins/coins.py:92 - missing: bitcoin defined in plugins/coins.py:92 - missing: eth defined in plugins/coins.py:97 - missing: ethereum defined in plugins/coins.py:97 - missing: doge defined in plugins/coins.py:106 - missing: band defined in plugins/lastfm.py:7 - missing: users defined in plugins/masshighlight.py:58 - missing: getusers defined in plugins/masshighlight.py:64 - missing: bots defined in plugins/system.py:94 - missing: source defined in plugins/system.py:99 - missing: kernel defined in plugins/kernel.py:8 - missing: distro defined in plugins/distro.py:80 - multiline: steamcalc defined in plugins/steam.py:72 - multiline: sc defined in plugins/steam.py:72 - missing: guts defined in plugins/stupid.py:138 - missing: plez defined in plugins/stupid.py:143 - missing: vendingmachine defined in plugins/stupid.py:451 - missing: shekels defined in plugins/stupid.py:522 - missing: hump defined in plugins/stupid.py:527 - missing: marry defined in plugins/stupid.py:533 - missing: pantsumap defined in plugins/stupid.py:540 - missing: penis defined in plugins/stupid.py:547 - missing: tits defined in plugins/stupid.py:566 - missing: vagina defined in plugins/stupid.py:585 - missing: anus defined in plugins/stupid.py:604 - missing: storyofpomfface defined in plugins/stupid.py:645 - missing: storyofrincewindscat defined in plugins/stupid.py:645 - missing: cowsay defined in plugins/stupid.py:657 - missing: hack defined in plugins/stupid.py:712 - missing: pdawg defined in plugins/stupid.py:717 - missing: leet defined in plugins/stupid.py:722 - missing: workout defined in plugins/stupid.py:758 - missing: pushups defined in plugins/stupid.py:768 - missing: squats defined in plugins/stupid.py:768 - missing: madoka defined in plugins/stupid.py:778 - missing: drink defined in plugins/stupid.py:783 - missing: fap defined in plugins/stupid.py:789 - missing: cayoot defined in plugins/stupid.py:800 - missing: spit defined in plugins/stupid.py:806 - missing: pee defined in plugins/stupid.py:812 - missing: sniff defined in plugins/stupid.py:818 - missing: lok defined in plugins/stupid.py:823 - missing: breakfast defined in plugins/stupid.py:862 - missing: rose defined in plugins/stupid.py:868 - missing: egg defined in plugins/stupid.py:876 - missing: banana defined in plugins/stupid.py:886 - missing: mango defined in plugins/stupid.py:891 - missing: peach defined in plugins/stupid.py:896 - missing: vax defined in plugins/stupid.py:901 - missing: yandere defined in plugins/booru.py:102 - missing: danbooru defined in plugins/booru.py:111 - missing: mask defined in plugins/core_admin_channel.py:15 - missing: match defined in plugins/core_admin_channel.py:47 - multiline: disable defined in plugins/core_admin_channel.py:302 - multiline: enable defined in plugins/core_admin_channel.py:324 - multiline: disablehash defined in plugins/core_admin_channel.py:360 - multiline: enablehash defined in plugins/core_admin_channel.py:396 - multiline: flood defined in plugins/core_admin_channel.py:449 - multiline: cmdflood defined in plugins/core_admin_channel.py:477 - multiline: trim defined in plugins/core_admin_channel.py:567 - multiline: mute defined in plugins/core_admin_channel.py:612 - multiline: unmute defined in plugins/core_admin_channel.py:621 - multiline: lock defined in plugins/core_admin_channel.py:664 - multiline: unlock defined in plugins/core_admin_channel.py:673 - multiline: ban defined in plugins/core_admin_channel.py:716 - multiline: kb defined in plugins/core_admin_channel.py:716 - multiline: unban defined in plugins/core_admin_channel.py:759 - multiline: ub defined in plugins/core_admin_channel.py:759 - multiline: kick defined in plugins/core_admin_channel.py:784 - multiline: kal defined in plugins/core_admin_channel.py:784 - multiline: k defined in plugins/core_admin_channel.py:784 - multiline: op defined in plugins/core_admin_channel.py:806 - multiline: up defined in plugins/core_admin_channel.py:806 - multiline: deop defined in plugins/core_admin_channel.py:818 - multiline: down defined in plugins/core_admin_channel.py:818 - multiline: hop defined in plugins/core_admin_channel.py:833 - multiline: dehop defined in plugins/core_admin_channel.py:843 - multiline: voice defined in plugins/core_admin_channel.py:853 - multiline: devoice defined in plugins/core_admin_channel.py:862 - multiline: invite defined in plugins/core_admin_channel.py:872 - missing: testdamnit defined in plugins/core_admin_channel.py:929 - multiline: nfl defined in plugins/nfl.py:50 - missing: ledzep defined in plugins/core_sieve.py:15 - missing: sudos defined in plugins/core_sieve.py:21 - missing: help defined in plugins/help.py:57 - missing: command defined in plugins/help.py:57 >>> PRIVMSG #chan :there are 114 commands that did not pass the test ```

flake8 output

``` > flake8 --ignore=E,W,M,Q --docstring-quotes=double --select=Q002 . .\calculator.py:111:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_channel.py:22:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_channel.py:634:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_channel.py:650:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_global.py:14:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_global.py:24:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_global.py:305:5: Q002 Single quote docstring found but double quotes preferred .\core_admin_global.py:336:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:9:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:37:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:66:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:95:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:118:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:141:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:164:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:187:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:210:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:234:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:306:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:333:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:357:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:380:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:403:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:426:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:453:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:481:5: Q002 Single quote docstring found but double quotes preferred .\core_user.py:508:5: Q002 Single quote docstring found but double quotes preferred .\countdown.py:22:5: Q002 Single quote docstring found but double quotes preferred .\countdown.py:73:5: Q002 Single quote docstring found but double quotes preferred .\datafiles.py:301:5: Q002 Single quote docstring found but double quotes preferred .\dice.py:19:5: Q002 Single quote docstring found but double quotes preferred .\dice.py:44:5: Q002 Single quote docstring found but double quotes preferred .\dictionary.py:14:5: Q002 Single quote docstring found but double quotes preferred .\dictionary.py:54:5: Q002 Single quote docstring found but double quotes preferred .\fmylife.py:25:5: Q002 Single quote docstring found but double quotes preferred .\hashtags.py:169:5: Q002 Single quote docstring found but double quotes preferred .\major_league_baseball.py:30:5: Q002 Single quote docstring found but double quotes preferred .\media.py:133:5: Q002 Single quote docstring found but double quotes preferred .\media.py:140:5: Q002 Single quote docstring found but double quotes preferred .\media.py:189:5: Q002 Single quote docstring found but double quotes preferred .\media.py:229:5: Q002 Single quote docstring found but double quotes preferred .\media.py:291:5: Q002 Single quote docstring found but double quotes preferred .\metacritic.py:14:5: Q002 Single quote docstring found but double quotes preferred .\mygengo_translate.py:48:5: Q002 Single quote docstring found but double quotes preferred .\namegen.py:53:5: Q002 Single quote docstring found but double quotes preferred .\quote.py:203:5: Q002 Single quote docstring found but double quotes preferred .\quote.py:311:5: Q002 Single quote docstring found but double quotes preferred .\religion.py:50:5: Q002 Single quote docstring found but double quotes preferred .\seen.py:1:1: Q002 Single quote docstring found but double quotes preferred .\stupid.py:152:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:213:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:466:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:473:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:480:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:487:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:494:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:502:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:512:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:518:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:628:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:636:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:671:5: Q002 Single quote docstring found but double quotes preferred .\stupid.py:679:5: Q002 Single quote docstring found but double quotes preferred .\tell.py:11:5: Q002 Single quote docstring found but double quotes preferred .\tell.py:56:5: Q002 Single quote docstring found but double quotes preferred .\tell.py:78:5: Q002 Single quote docstring found but double quotes preferred .\weather.py:35:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:49:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:119:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:156:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:163:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:170:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:177:5: Q002 Single quote docstring found but double quotes preferred .\_broken\anime.py:189:5: Q002 Single quote docstring found but double quotes preferred .\_broken\rss.py:7:5: Q002 Single quote docstring found but double quotes preferred .\_broken\rss.py:39:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\bf.py:1:1: Q002 Single quote docstring found but double quotes preferred .\_disabled\bf.py:17:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\domains.py:60:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\dotnetpad.py:1:1: Q002 Single quote docstring found but double quotes preferred .\_disabled\dotnetpad.py:12:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\dotnetpad.py:48:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\dotnetpad.py:55:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\fact.py:6:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\fishbans.py:10:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\fishbans.py:30:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\gainz.py:13:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\isdown.py:8:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\mcitems.py:54:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\mcitems.py:86:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\mcwiki.py:10:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\mtg.py:8:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\munge.py:6:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\perl.py:6:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\ping.py:13:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\ping.py:34:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\pre.py:8:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\rottentomatoes.py:10:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\somethingawful.py:8:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\steam.py:11:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\steam.py:19:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\steam.py:60:5: Q002 Single quote docstring found but double quotes preferred .\_disabled\suggest.py:10:5: Q002 Single quote docstring found but double quotes preferred .\_unused\lmgtfy.py:8:5: Q002 Single quote docstring found but double quotes preferred .\_unused\rottentomatoes.py:12:5: Q002 Single quote docstring found but double quotes preferred .\_unused\shorten.py:6:5: Q002 Single quote docstring found but double quotes preferred .\util\text.py:14:5: Q002 Single quote docstring found but double quotes preferred .\util\text.py:103:5: Q002 Single quote docstring found but double quotes preferred .\util\text.py:325:5: Q002 Single quote docstring found but double quotes preferred ```

[ineeee]

i've decided to enforce the docstring syntax to be ^([a-z0-9]+)( <[0-9a-z #@|]+>| \[[0-9a-z #@|]+\])*( -- |: )(.+)$. this translates to command <required> [optional] -- description.

progress

outdated, see next comment

``` - format: weather defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: forecast defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: w defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: t defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: time defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: alerts defined in plugins/weather.py:28 weather/time/alerts | [save] | <@ user> -- Gets weather data for . - format: geoip defined in plugins/geoip.py:17 geoip -- Gets the location of - format: reminder defined in plugins/reminder.py:4 reminder --- reminds you of . - format: remind defined in plugins/reminder.py:4 reminder --- reminds you of . - format: desktop defined in plugins/core_user.py:35 desktop http://url.to/desktop | @ nick -- Shows a users Desktop. - format: birthday defined in plugins/core_user.py:232 birthday <01/01/2001> | <@ person> -- Shows a users Birthday. - format: series defined in plugins/media.py:129 .tv -- get info for the - format: show defined in plugins/media.py:129 .tv -- get info for the - format: tv defined in plugins/media.py:129 .tv -- get info for the - format: tv_next defined in plugins/media.py:137 .tv_next -- get the next episode of - format: next defined in plugins/media.py:137 .tv_next -- get the next episode of - format: last defined in plugins/media.py:184 .tv_last -- gets the most recently aired episode of - format: prev defined in plugins/media.py:184 .tv_last -- gets the most recently aired episode of - format: tv_prev defined in plugins/media.py:184 .tv_last -- gets the most recently aired episode of - format: tv_last defined in plugins/media.py:184 .tv_last -- gets the most recently aired episode of - format: rottentomatoes defined in plugins/media.py:288 .rt