Modifications all over the place, but mainly only to update Doxygen documentation

git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@515 74dad513-b988-da41-8d7b-12977e46ad98

5 files changed, 200 insertions, 41 deletions

diff --git a/pjsip/docs/doxygen.cfg b/pjsip/docs/doxygen.cfg
index f1d26386..3edc5bfc 100644
--- a/pjsip/docs/doxygen.cfg
+++ b/pjsip/docs/doxygen.cfg
@@ -134,7 +134,7 @@ FULL_PATH_NAMES        = NO
 # the path. It is allowed to use relative paths in the argument list.

 

 #STRIP_FROM_PATH        = "/cygdrive/e/project/bulukucing.org/pjsip/src"

-STRIP_FROM_PATH        = "/c/project/bulukucing.org/pjsip/src"

+STRIP_FROM_PATH        = "/c/project/pjproject/pjsip"

 

 # The INTERNAL_DOCS tag determines if documentation 

 # that is typed after a \internal command is included. If the tag is set 

@@ -346,7 +346,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 

 # with spaces.

 

-INPUT                  =  src/pjsip src/pjsip_mod_ua src/pjsip_simple src

+INPUT                  =  docs include 

 

 # If the value of the INPUT tag contains directories, you can use the 

 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

@@ -474,7 +474,7 @@ COLS_IN_ALPHA_INDEX    = 5
 # The IGNORE_PREFIX tag can be used to specify one or more prefixes that 

 # should be ignored while generating the index headers.

 

-IGNORE_PREFIX          = 

+IGNORE_PREFIX          =  /c/project/pjproject/pjsip

 

 #---------------------------------------------------------------------------

 # configuration options related to the HTML output

@@ -495,19 +495,19 @@ HTML_OUTPUT            = html
 # each generated HTML page (for example: .htm,.php,.asp). If it is left blank 

 # doxygen will generate files with .html extension.

 

-HTML_FILE_EXTENSION    = .html

+HTML_FILE_EXTENSION    = .htm

 

 # The HTML_HEADER tag can be used to specify a personal HTML header for 

 # each generated HTML page. If it is left blank doxygen will generate a 

 # standard header.

 

-HTML_HEADER            = 

+HTML_HEADER            =  docs/header.html

 

 # The HTML_FOOTER tag can be used to specify a personal HTML footer for 

 # each generated HTML page. If it is left blank doxygen will generate a 

 # standard footer.

 

-HTML_FOOTER            = 

+HTML_FOOTER            =  docs/footer.html

 

 # The HTML_STYLESHEET tag can be used to specify a user defined cascading 

 # style sheet that is used by each HTML page. It can be used to 

@@ -844,7 +844,6 @@ INCLUDE_FILE_PATTERNS  =
 

 

 PREDEFINED             = PJ_DECL(x)=x PJ_DEF(x)=x PJ_IDECL(x)=x \

-

 			 PJ_IDEF(x)=x PJ_INLINE(x)=x

 

 

@@ -1010,37 +1009,3 @@ DOT_CLEANUP            = YES
 

 SEARCHENGINE           = NO

 

-# The CGI_NAME tag should be the name of the CGI script that 

-# starts the search engine (doxysearch) with the correct parameters. 

-# A script with this name will be generated by doxygen.

-

-CGI_NAME               = search.cgi

-

-# The CGI_URL tag should be the absolute URL to the directory where the 

-# cgi binaries are located. See the documentation of your http daemon for 

-# details.

-

-CGI_URL                = 

-

-# The DOC_URL tag should be the absolute URL to the directory where the 

-# documentation is located. If left blank the absolute path to the 

-# documentation, with file:// prepended to it, will be used.

-

-DOC_URL                = 

-

-# The DOC_ABSPATH tag should be the absolute path to the directory where the 

-# documentation is located. If left blank the directory on the local machine 

-# will be used.

-

-DOC_ABSPATH            = 

-

-# The BIN_ABSPATH tag must point to the directory where the doxysearch binary 

-# is installed.

-

-BIN_ABSPATH            = /usr/local/bin/

-

-# The EXT_DOC_PATHS tag can be used to specify one or more paths to 

-# documentation generated for other projects. This allows doxysearch to search 

-# the documentation for these projects as well.

-

-EXT_DOC_PATHS          = 

diff --git a/pjsip/docs/doxygen.h b/pjsip/docs/doxygen.h
new file mode 100644
index 00000000..d13ae200
--- /dev/null
+++ b/pjsip/docs/doxygen.h
@@ -0,0 +1,183 @@
+/* $Id$ */
+/* 
+ * Copyright (C) 2003-2006 Benny Prijono <benny@prijono.org>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
+ */
+
+/**
+ * @file doxygen.h
+ * @brief PJSIP Doxygen's mainpage.
+ */
+
+/*////////////////////////////////////////////////////////////////////////// */
+/*
+	INTRODUCTION PAGE
+ */
+
+/**
+
+  @mainpage PJSIP
+
+  \n
+  \n
+  @section intro_sec Introduction
+
+  PJSIP is an Open Source SIP prototol stack, designed to be very small in 
+  footprint, have high performance, and very flexible.
+
+  @subsection hist_sec History
+
+  PJSIP has been actively developed since 2003, but its history goes well
+  beyond that. The author has been developing SIP stack since 1999 during
+  RFC 2543 era, and after several experimentation with different approaches 
+  in the programming (the first stack actually was in C++!), and also with
+  the evolution of the SIP protocol itself, the current/third generation
+  of PJSIP (the 0.2.9 version is the second generation) can be considered 
+  as pretty stable in term of design, and should
+  incorporate all design considerations (and implementation tricks!) that 
+  have been learned over the years. Of course only time will tell if this 
+  statement can still be held true in the future.
+
+
+
+
+  \n
+  \n
+  @section pjsipgetting_started Getting Started
+
+  PJSIP consists of multiple levels of APIs, which each of them layered on
+  top of another. Because of this, new readers may find it a bit difficult
+  to find the place to start.
+
+  In general, I think perhaps I can recommend two approaches on using PJSIP.
+
+
+  \n
+  @subsection getting_started_high Using PJSUA API
+
+  @ref PJSUA_LIB wraps together all SIP components and media into a high level
+  API, suitable for creating typical SIP user agent applications. It 
+  features easy to use API for:
+  - multiple client registration (accounts),
+  - high level SIP and media session (calls),
+  - buddy list, presence and instant messaging,
+  - powerful and very easy to use media manipulation,
+
+  while maintaining some space for customization (custom SIP
+  transport, custom SIP media, etc.) needed by some types of applications.
+  @ref PJSUA_LIB is also aimed to be able to run on devices such as PDA
+  or mobile phones, by carefully allowing application to set the appropriate
+  threading strategy and memory limits (number of calls, media ports, etc.).
+
+  However, @ref PJSUA_LIB may not be the most suitable API for some types
+  of applications, since it is directed towards an easy to use API. For
+  more more advanced use, you may better implement the application by using
+  PJSIP + PJMEDIA directly, as described below.
+
+
+  \n
+  @subsection getting_started_pjsip_pjmedia Using PJSIP and PJMEDIA Directly
+
+  For the ultimate flexibility and power, using PJSIP and PJMEDIA directly
+  is the way to go. The drawback will be, of course, steeper learning curve. 
+
+  However, the following links may provide some useful information:
+  - <A HREF="/docs.htm">PJSIP Developer's Guide</A> PDF
+    document is the ultimate guide to understand PJSIP design concept.
+  - there are some samples in <A HREF="/cgi-bin/viewcvs.cgi/pjproject/trunk/pjsip-apps/src/samples/">
+   <b>pjsip-apps/src/samples</b></A> directory.
+  - @ref PJSUA_LIB source code may also be useful to see how high level
+    API are implemented with PJSIP/PJMEDIA.
+  - and finally, you can always <b>Use the Source</b>!
+
+
+
+  \n
+  \n
+  @section this_doc About This Document
+
+  This document contains the reference information about PJSIP. For
+  more in-depth guide (and information in general), readers are 
+  encouraged to read the <A HREF="/docs.htm">
+  <b>PJSIP Developer's Guide</b></A> PDF document
+  which can be downloaded from http://www.pjsip.org/docs.htm.
+
+  \n
+  @subsection doc_ver Version
+
+  This document corresponds to PJSIP version 0.5.6.
+
+  \n
+  @subsection doc_how_to_read How to Read This Document
+
+  For main navigation, please go to <A HREF="modules.htm"><b>Modules</b></A>
+  link on top of this page.
+
+  This document was generated with <A HREF="http://www.doxygen.org">Doxygen</A>
+  from PJSIP header files.
+
+
+  \n
+  \n
+  @section pjsip_toc Documentation Contents
+
+  Click on <A HREF="modules.htm"><b>Modules</b></A> link on top of this page 
+  to get the detailed table of contents.
+
+  The following are top level sections in the <A HREF="modules.htm">
+  <b>Modules</b></A>, as laid out in the following diagram:
+
+  \image html pjsip-arch.jpg "Static Library Layout"
+
+  Enumerating the static libraries from the bottom:
+
+  - <A HREF="/pjlib/docs/main.htm">PJLIB</A>, is the platform abstraction
+    and framework library, on which all other libraries depend,
+
+  - PJLIB-UTIL, provides auxiliary functions such as text scanning,
+    XML, and STUN,
+
+  - PJMEDIA is the multimedia framework,
+
+  - PJMEDIA-CODEC is the placeholder for media codecs,
+
+  - @ref PJSIP_CORE (<b>PJSIP-CORE</b>) is the very core of the PJSIP library, 
+    and contains the SIP @ref PJSIP_ENDPT, which is the owner/manager for all
+    SIP objects in the application, messaging elements, parsing, transport 
+    management, module management, and stateless operations, and also
+    contains:
+
+  - The @ref PJSIP_TRANSACT module inside <b>PJSIP-CORE</b> provides 
+    stateful operation, and is the base for higher layer features such as 
+    dialogs,
+
+  - The @ref PJSIP_UA module inside <b>PJSIP-CORE</b> manages dialogs, and supports dialog
+    usages,
+
+  - @ref PJSIP_SIMPLE (<b>PJSIP-SIMPLE</b>) provides the base SIP event framework 
+    (which uses the common/base dialog framework) and implements presence 
+    on top of it, and is also used by call transfer functions,
+
+  - @ref PJSIP_HIGH_UA (<b>PJSIP-UA</b>) is the high level abstraction of INVITE sessions
+    (using the common/base dialog framework). This library also provides
+    SIP client registration and call transfer functionality,
+
+  - and finally, @ref PJSUA_LIB (<b>PJSUA-LIB</b>) is the highest level of abstraction, 
+    which wraps together all above functionalities into high level, easy to
+    use API.
+*/
+
+
diff --git a/pjsip/docs/footer.html b/pjsip/docs/footer.html
new file mode 100644
index 00000000..7e7b5529
--- /dev/null
+++ b/pjsip/docs/footer.html
@@ -0,0 +1,4 @@
+	<!--#include virtual="/footer.html" -->

+

+</BODY>

+</HTML>

diff --git a/pjsip/docs/header.html b/pjsip/docs/header.html
new file mode 100644
index 00000000..9faaf8d8
--- /dev/null
+++ b/pjsip/docs/header.html
@@ -0,0 +1,7 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

+<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">

+<title>PJSIP - Open Source SIP, SIMPLE, Presence, IM Protocol Stack Documentation</title>

+<link href="/style/style.css" rel="stylesheet" type="text/css">

+</head><body>

+	<!--#include virtual="/header.html" -->

+

diff --git a/pjsip/docs/pjsip-arch.jpg b/pjsip/docs/pjsip-arch.jpg
new file mode 100644
index 00000000..c591823e
--- /dev/null
+++ b/pjsip/docs/pjsip-arch.jpg