Merge pull request #1 from cburgard/main

add doxygen documentation

Author: nonchris

Doxyfile

@@ -34,4 +34,7 @@ https://github.com/Info-Bonn/poll-bot
 I collected the most useful and generic functions to save me some time when starting the next bot-project. 
 
 ### dependencies 
-This project is based on `discord.py V1.x` minimum required: V1.5.1
+This project is based on `discord.py V1.x` minimum required: V1.5.1
+
+### documentation
+In order to render this documentation, just call `doxygen`

README.md

@@ -4,17 +4,15 @@
 import utils as utl
 from environment import OWNER_NAME, OWNER_ID, VERSION, PREFIX
 
-"""
-This custom help command is a replacement for the default one on any Discord Bot written in discord.py!
-However, you must put "bot.remove_command('help')" in your bot, and the command must be in a cog for it to work.
-
-Original concept by Jared Newsom (AKA Jared M.F.)
-[link no longer available] https://gist.github.com/StudioMFTechnologies/ad41bfd32b2379ccffe90b0e34128b8b 
-Rewritten and optimized by https://github.com/nonchris
-https://gist.github.com/nonchris/1c7060a14a9d94e7929aa2ef14c41bc2
-
-This version relies more on the structure around this module than the gist does, which is more 'stand alone'
-"""
+### @package help
+# 
+# This custom help command is a replacement for the default one on any Discord Bot written in discord.py!
+# However, you must put "bot.remove_command('help')" in your bot, and the command must be in a cog for it to work.
+# 
+# Original concept by [Jared Newsom (AKA Jared M.F.)](https://gist.github.com/StudioMFTechnologies/ad41bfd32b2379ccffe90b0e34128b8b)
+# Rewritten and optimized by [nonchris](https://github.com/nonchris)
+# 
+# This version relies more on the structure around this module than the gist does, which is more 'stand alone'
 
 
 class Help(commands.Cog):
@@ -23,12 +21,22 @@ class Help(commands.Cog):
     """
 
     def __init__(self, bot):
+        """! 
+        Constructor
+
+        @param bot The bot instance to be used.
+        """
         self.bot = bot
 
     @commands.command(aliases=['h', 'hilfe'])
     # @commands.bot_has_permissions(add_reactions=True,embed_links=True)
     async def help(self, ctx, *params):
-        """Shows all modules of that bot"""
+        """!
+        Shows all modules of that bot
+        
+        @param ctx Context of the message.
+        @param params further arguments
+        """
 
         # checks if cog parameter was given
         # if not: sending all modules and commands not associated with a cog
@@ -121,4 +129,9 @@ async def help(self, ctx, *params):
 
 
 def setup(bot):
+    """!
+    Setup a bot.
+
+    @param bot The bot to setup.
+    """
     bot.add_cog(Help(bot))

src/cogs/help.py

@@ -4,6 +4,11 @@
 import utils as ut
 
 
+### @package misc
+#
+# Collection of miscellaneus helpers.
+#
+
 class Misc(commands.Cog):
     """
     Various useful Commands for everyone
@@ -14,6 +19,11 @@ def __init__(self, bot):
 
     @commands.command(name='ping', help="Check if Bot available")
     async def ping(self, ctx):
+        """!
+        ping to check if the bot is available
+
+        @param ctx Context of the message
+        """
         print(f"ping: {round(self.bot.latency * 1000)}")
 
         await ctx.send(
@@ -24,4 +34,4 @@ async def ping(self, ctx):
 
 
 def setup(bot):
-    bot.add_cog(Misc(bot))
+    bot.add_cog(Misc(bot))

src/cogs/misc.py

@@ -1,14 +1,18 @@
 import os
 import logging
 
+### @package environment
+#
+# Interacitons with the environment variables.
+#
 
 def load_env(key: str, default: str) -> str:
-    """
+    """!
     os.getenv() wrapper that handles the case of None-types for not-set env-variables\n
 
-    :param key: name of env variable to load
-    :param default: default value if variable couldn't be loaded
-    :return: value of env variable or default value
+    @param key: name of env variable to load
+    @param default: default value if variable couldn't be loaded
+    @return value of env variable or default value
     """
     value = os.getenv(key)
     if value:

src/environment.py

@@ -1,6 +1,11 @@
 import os
 import logging
 
+### @package log_setup
+#
+# Setup of logging
+#
+
 # path for databases or config files
 if not os.path.exists('data/'):
     os.mkdir('data/')

src/log_setup.py

@@ -1,3 +1,4 @@
+#!/bin/env python
 import os
 
 import discord
@@ -20,6 +21,9 @@
 # login message
 @bot.event
 async def on_ready():
+    """!
+    function called when the bot is ready. emits the '[Bot] has connected' message
+    """
     print(f'{bot.user.name} has connected')
 
     logger.info(f"Bot has connected, active on {len(bot.guilds)} guilds")

src/main.py

@@ -1,24 +1,31 @@
 import discord
 from discord.errors import Forbidden
 
-"""
-The color presets, send_message() and make_embed() functions are included in the discord-bot template by nonchris
-https://github.com/nonchris/discord-bot
-"""
+### @package utils
+#
+# The color presets, send_message() and make_embed() functions are
+# included in the [discord-bot template by
+# nonchris](https://github.com/nonchris/discord-bot)
 
 
 # color scheme for embeds as rbg
 blue_light = discord.Color.from_rgb(20, 255, 255)  # default color
 green = discord.Color.from_rgb(142, 250, 60)   # success green
-yellow = discord.Color.from_rgb(245, 218, 17)  # waring like 'hey, that's not cool'
-orange = discord.Color.from_rgb(245, 139, 17)  # waring - rather critical like 'no more votes left'
+yellow = discord.Color.from_rgb(245, 218, 17)  # warning like 'hey, that's not cool'
+orange = discord.Color.from_rgb(245, 139, 17)  # warning - rather critical like 'no more votes left'
 red = discord.Color.from_rgb(255, 28, 25)      # error red
 
+### @package utils
+#
+# Utilities and helper functions
+#
 
 async def send_embed(ctx, embed):
-    """
+    """!
     Handles the sending of embeds
-    -> Takes context and embed to send
+    @param ctx context to send to
+    @param embed embed to send
+
     - tries to send embed in channel
     - tries to send normal message when that fails
     - tries to send embed private with information abot missing permissions
@@ -35,18 +42,17 @@ async def send_embed(ctx, embed):
                 f"May you inform the server team about this issue? :slight_smile:", embed=embed)
 
 
-# creating and returning an embed with keyword arguments
-# please note that name and value can't be empty - name and value contain a zero width non-joiner
 def make_embed(title="", color=blue_light, name="‌", value="‌", footer=None) -> discord.Embed:
-    """
+    """!
     Function to generate generate an embed in one function call
-
-    :param title: Headline of embed
-    :param color: RGB Tuple (Red, Green, Blue)
-    :param name: Of field (sub-headline)
-    :param value: Text of field (actual text)
-    :param footer: Text in footer
-    :return: Embed ready to send
+    please note that name and value can't be empty - name and value contain a zero width non-joiner
+
+    @param title Headline of embed
+    @param color RGB Tuple (Red, Green, Blue)
+    @param name: Of field (sub-headline)
+    @param value: Text of field (actual text)
+    @param footer: Text in footer
+    @return Embed ready to send
     """
     # make color object
     emb = discord.Embed(title=title, color=color)