From 95d5f3822208edf2fe7c38840c839dab0807060a Mon Sep 17 00:00:00 2001
From: drbob <retroshare.project@gmail.com>
Date: Fri, 17 Oct 2008 22:41:31 +0000
Subject: [PATCH] Added more comments describing how to start up libretroshare

git-svn-id: http://svn.code.sf.net/p/retroshare/code/trunk@752 b45a01b8-16f6-495d-af2f-9b41ad6348cc
---
 libretroshare/src/rsiface/retroshare.cc | 46 +++++++++++++++++++++++--
 1 file changed, 44 insertions(+), 2 deletions(-)

diff --git a/libretroshare/src/rsiface/retroshare.cc b/libretroshare/src/rsiface/retroshare.cc
index 7510779c9..55a1d125f 100644
--- a/libretroshare/src/rsiface/retroshare.cc
+++ b/libretroshare/src/rsiface/retroshare.cc
@@ -35,20 +35,62 @@
 #endif
                                 
 
+/* Basic instructions for running libretroshare as background thread.
+ * ******************************************************************* *
+ * This allows your program to communicate with authenticated peers. 
+ *
+ * libretroshare's interfaces are defined in libretroshare/src/rsiface.
+ * This should be the only headers that you need to include.
+ *
+ * The startup routine's are defined in rsiface.h
+ */
+
 int main(int argc, char **argv)
 {
-	/* Objects */
+	/* Retroshare startup is configured using an RsInit object.
+	 * This is an opaque class, which the user cannot directly tweak
+	 * If you want to peek at whats happening underneath look in
+	 * libretroshare/src/rsserver/p3face-startup.cc
+	 *
+	 * You create it with InitRsConfig(), and delete with CleanupRsConfig()
+	 * InitRetroshare(argv, argc, config) parses the command line options, 
+	 * and initialises the config paths.
+	 *
+	 * *** There are several functions that I should add to modify 
+	 * **** the config the moment these can only be set via the commandline 
+	 *   - RsConfigDirectory(...) is probably the most useful.
+	 *   - RsConfigNetAddr(...) for setting port, etc.
+	 *   - RsConfigOutput(...) for logging and debugging.
+	 *
+	 * Next you need to worry about loading your certificate, or making
+	 * a new one:
+	 *
+	 *   RsGenerateCertificate(...) To create a new key, certificate 
+	 *   LoadPassword(...) set password for existing certificate.
+	 **/
+
 	RsInit *config = InitRsConfig();
 	InitRetroShare(argc, argv, config);
+
+	 /* load password should be called at this point: LoadPassword()
+	  * otherwise loaded from commandline.
+	  */
+
+	 /* Key + Certificate are loaded into libretroshare */
 	LoadCertificates(config, false);
 
-	//NotifyBase *notify = new NotifyBase();
+	/* Now setup the libretroshare interface objs 
+	 * You will need to create you own NotifyXXX class
+	 * if you want to receive notifications of events */
+
 	NotifyTxt *notify = new NotifyTxt();
 	RsIface *iface = createRsIface(*notify);
         RsControl *rsServer = createRsControl(*iface, *notify);
 
 	notify->setRsIface(iface);
 
+	/* Start-up libretroshare server threads */
+
 	rsServer -> StartupRetroShare(config);
 	CleanupRsConfig(config);