Revision 2:e4c74eb20586, committed 2014-08-02

Comitter:

NickRyder

Date:

Sat Aug 02 12:57:57 2014 +0000

Parent:

1:cf586c9bbb52

Commit message:

Added documentation.

Changed in this revision

diff -r cf586c9bbb52 -r e4c74eb20586 IrcBot.cpp
--- a/IrcBot.cpp	Sat Aug 02 12:17:28 2014 +0000
+++ b/IrcBot.cpp	Sat Aug 02 12:57:57 2014 +0000
@@ -12,7 +12,7 @@
     msg[0] = '\0';
 }
 
-Irc::Irc(char * nick, char * net, int p, char * chan) :
+IrcBot::IrcBot(char * nick, char * net, int p, char * chan) :
         pc(USBTX, USBRX), sock(), port(p), ident(false), connected(false),
         setup(false), joined(false), parseindex(0)
 {
@@ -20,28 +20,17 @@
     sprintf(password, "%s", "");
     sprintf(network, "%s", net);
     sprintf(channel, "%s", chan);
-    pc.printf("Created Irc obj for %s.\n", nickname);
-}
-
-void Irc::identify(char * pass) {
-    ident = true;
-    sprintf(password, "%s", pass);    
+    pc.printf("Created IrcBot obj for %s.\n", nickname);
 }
 
-void Irc::join(char * chan) {
-    char cmd[64];
-    sprintf(cmd, ":source JOIN :%s\r\n", chan);
-    send(cmd);
-}
-
-void Irc::connect() {
+void IrcBot::connect() {
     pc.printf("Connecting to %s:%d...\n", network, port);
     sock.connect(network, port);
     pc.printf("Done.\n");
     connected = true;
 }
 
-void Irc::disconnect() {
+void IrcBot::disconnect() {
     if (connected) {
         pc.printf("Disconnecting.\n");
         sock.close();
@@ -49,11 +38,11 @@
     }
 }
 
-void Irc::add(MessageHandler * handler) {
+void IrcBot::add(MessageHandler * handler) {
     handlers.push_back(handler);
 }
 
-bool Irc::read() {
+bool IrcBot::read() {
     if (!connected) return 0;
     int ret = sock.receive(readbuffer, sizeof(readbuffer) - 1);
     bool parsed = false;
@@ -74,7 +63,7 @@
     return parsed;
 }
 
-void Irc::send(char * cmd) {
+void IrcBot::send(char * cmd) {
     if (!connected) return;
     int i = 0;
     bool ok = true;
@@ -90,7 +79,7 @@
     sock.send_all(cmd, i);
 }
 
-void Irc::handle(IrcMessage msg) {
+void IrcBot::handle(IrcMessage msg) {
     pc.printf("Handling message from %s, to %s: %s\n", msg.from, msg.to, msg.msg);    
     for (int i = 0; i < handlers.size(); i++) {
         IrcMessage out = handlers.at(i)->handle(msg);
@@ -104,7 +93,7 @@
     }
 }
 
-void Irc::parse() {
+void IrcBot::parse() {
     pc.printf("Parsing: --%s--\n", parsebuffer);
     if (setup && (!joined)) {
         char cmd[256];

diff -r cf586c9bbb52 -r e4c74eb20586 IrcBot.h
--- a/IrcBot.h	Sat Aug 02 12:17:28 2014 +0000
+++ b/IrcBot.h	Sat Aug 02 12:57:57 2014 +0000
@@ -5,27 +5,62 @@
 #include "EthernetInterface.h"
 #include <vector>
 
+/** 
+ * IrcBot responds to commands on IRC using message users' handlers
+ */ 
 class IrcMessage {
     public:
+        /** Create empty IrcMessage */
         IrcMessage();
-        IrcMessage(char *, char *, char *);    
+        
+        /** Create an IrcMessage
+         * @param from The user sending the message.
+         * @param to The user/channel receiving the message.
+         * @param message The message.
+         */ 
+        IrcMessage(char * from, char * to, char * message);    
         char from[32], to[32], msg[256];
 };
 
+/**
+ * Base MessageHandler class.
+ * Users should write classes inheriting from MessageHandler to parse and 
+ * respond to incoming IRC messages.
+ */
 class MessageHandler {
     public:
         MessageHandler() {};
         virtual IrcMessage handle(IrcMessage msg) {return IrcMessage();}
 };
 
-class Irc {
+/**
+ * IrcBot connects to an IRC network and joins a channel. Users can add message
+ * handlers which parse incoming private messages and respond to them.
+ */
+class IrcBot {
     public:
-        Irc(char *, char *, int, char *);
+        /** Create an IrcBot
+         *
+         * @param nickname Bot's nickname
+         * @param network IRC network to join
+         * @param port Port to connect to network on
+         * @param channel Channel to connect to
+         */
+        IrcBot(char * nickname, char * network, int port, char * channel);
+        /** Connect to the network. 
+         *
+         * Users should have already created a network interface 
+         * (Ethernet/Wifi/3G/whatever) to carry the connection.
+         */ 
         void connect();
+        /// Disconnect from the network.
         void disconnect();
+        /// Add a handler for incoming messages.
         void add(MessageHandler *);
-        void identify(char *);
-        void join(char *);
+        
+        /** Read data from internet connection, parse input and handle any
+         * incoming private messages
+         */
         bool read();
     private:
         void handle(IrcMessage);

diff -r cf586c9bbb52 -r e4c74eb20586 IrcMessageHandlers.h
--- a/IrcMessageHandlers.h	Sat Aug 02 12:17:28 2014 +0000
+++ b/IrcMessageHandlers.h	Sat Aug 02 12:57:57 2014 +0000
@@ -2,9 +2,16 @@
 #define __mbed_irc_handlers_h__
 #include "IrcBot.h"
 
+///  DigitalOutHandler lets users control a DigitalOut using "WRITE <name> ON/OFF"
 class DigitalOutHandler : private MessageHandler {
     public:
-        DigitalOutHandler(char *, PinName, bool);
+        /** Create a DigitalOutHandler
+         * @param name Name of output used in command on IRC
+         * @param pin Pin the output is connected to.
+         * @param verbose Whether or not a reply is sent to IRC confirming the output state
+         */
+        DigitalOutHandler(char * name, PinName pin, bool verbose);
+        /// Set output pin on or off, reply "SET <name> ON/OFF" if verbose.
         IrcMessage handle(IrcMessage);
     private:
         DigitalOut pin;
@@ -12,19 +19,35 @@
         bool verbose;
 };
 
+///  DigitalInHandler lets users read a DigitalIn using "READ <name>"
 class DigitalInHandler : private MessageHandler {
     public:
-        DigitalInHandler(char *, PinName);
+        /** Create a DigitalInHandler
+         * @param name Name of input used in command on IRC
+         * @param pin Pin the input is connected to.
+         */
+        DigitalInHandler(char * name, PinName pin);
+        /// Reply "<name> IS ON/OFF"
         IrcMessage handle(IrcMessage);
     private:
         DigitalIn pin;
         char name[32];
 };
 
+///  AnalogInHandler lets users read a DigitalIn using "READ <name>"
 class AnalogInHandler : private MessageHandler {
     public:
-        AnalogInHandler(char *, PinName);
-        void scale(float, char *);
+        /** Create an AnalogInHandler
+         * @param name Name of input used in command on IRC
+         * @param pin Pin the input is connected to.
+         */
+        AnalogInHandler(char * name, PinName pin);
+        /** Define a scaling factor for the measured value [0.0 - 1.0]
+         * @param scale The scaling factor
+         * @param unit The units used in the message to IRC
+         */
+        void scale(float scale, char * unit);
+        /// Measure input, scale and reply "<name> = <value> <units>"
         IrcMessage handle(IrcMessage);
     private:
         AnalogIn pin;
@@ -33,9 +56,11 @@
         float scaleval;
 };
 
+/// A handler to echo back any messages of the form "ECHO <x>"
 class EchoHandler : private MessageHandler {
     public:
         EchoHandler(){};
+        /// Reply to "ECHO <x>" with "<x>"
         IrcMessage handle(IrcMessage msg);
 };