Docs: more fixes on sample/source links (#3675)

2023-09-06 09:56:26 +07:00 · 2023-09-06 09:56:26 +07:00 · eff4826803
parent e17b92b973
commit eff4826803
17 changed files with 43 additions and 26 deletions
--- a/pjlib-util/docs/doxygen.cfg
+++ b/pjlib-util/docs/doxygen.cfg
@ -259,6 +259,10 @@ GENERATE_DEPRECATEDLIST= YES
 # You can put \n's in the value part of an alias to insert newlines.

 ALIASES                = 
+ALIASES               += src{1}="\verbatim embed:rst:inline :source:`\1` \endverbatim"
+ALIASES               += srcdir{1}="\verbatim embed:rst:inline :sourcedir:`\1` \endverbatim"
+ALIASES               += img{1}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" />"
+ALIASES               += img{2}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" alt=\"\2\" />"

 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
--- a/pjlib/docs/doxygen.cfg
+++ b/pjlib/docs/doxygen.cfg
@ -260,7 +260,10 @@ GENERATE_DEPRECATEDLIST= YES

 ALIASES                = 
 ALIASES               += src{1}="\verbatim embed:rst:inline :source:`\1` \endverbatim"
-
+ALIASES               += srcdir{1}="\verbatim embed:rst:inline :sourcedir:`\1` \endverbatim"
+ALIASES               += img{1}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" />"
+ALIASES               += img{2}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" alt=\"\2\" />"
+ 
 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.

--- a/pjlib/include/pj/except.h
+++ b/pjlib/include/pj/except.h
@ -40,8 +40,8 @@ PJ_BEGIN_DECL
 * \section pj_except_sample_sec Quick Example
 *
 * For the impatient, take a look at some examples:
- *  - @ref page_pjlib_samples_except_c
- *  - @ref page_pjlib_exception_test
+ *  - Exception Handling sample: \src{pjlib/src/pjlib-samples/except.c}
+ *  - Exception Handling test: \src{pjlib/src/pjlib-test/exception.c}
 *
 * \section pj_except_except Exception Handling
 *
@ -217,8 +217,8 @@ PJ_BEGIN_DECL
 * \section pj_except_examples_sec Examples
 *
 * For some examples on how to use the exception construct, please see:
- *  - @ref page_pjlib_samples_except_c
- *  - @ref page_pjlib_exception_test
+ *  - Exception Handling sample: \src{pjlib/src/pjlib-samples/except.c}
+ *  - Exception Handling test: \src{pjlib/src/pjlib-test/exception.c}
 */

 /**
--- a/pjlib/include/pj/list.h
+++ b/pjlib/include/pj/list.h
@ -47,8 +47,8 @@ PJ_BEGIN_DECL
 * \section pj_list_example_sec Examples
 *
 * See below for examples on how to manipulate linked list:
- *  - @ref page_pjlib_samples_list_c
- *  - @ref page_pjlib_list_test
+ *  - List sample: \src{pjlib/src/pjlib-samples/list.c}
+ *  - List test: \src{pjlib/src/pjlib-test/list.c}
 */


--- a/pjlib/include/pj/log.h
+++ b/pjlib/include/pj/log.h
@ -59,7 +59,7 @@ PJ_BEGIN_DECL
 * \section pj_log_quick_sample_sec Examples
 *
 * For examples, see:
- *  - @ref page_pjlib_samples_log_c.
+ *  - Simple Log sample: \src{pjlib/src/pjlib-samples/log.c}
 *
 */

--- a/pjlib/include/pj/os.h
+++ b/pjlib/include/pj/os.h
@ -608,7 +608,7 @@ PJ_DECL(void*) pj_thread_local_get(long index);
 * \section pj_atomic_examples_sec Examples
 *
 * For some example codes, please see:
- *  - @ref page_pjlib_atomic_test
+ *  - Atomic Variable test: \src{pjlib/src/pjlib-test/atomic.c}
 */


--- a/pjlib/include/pj/pool.h
+++ b/pjlib/include/pj/pool.h
@ -276,7 +276,7 @@ PJ_BEGIN_DECL
 * \section PJ_POOL_EXAMPLES_SEC Examples
 *
 * For some sample codes on how to use the pool, please see:
- *  - @ref page_pjlib_pool_test
+ *  - Pool test: \src{pjlib/src/pjlib-test/pool.c}
 *
 * @{
 */
--- a/pjlib/include/pj/string.h
+++ b/pjlib/include/pj/string.h
@ -65,7 +65,7 @@ PJ_BEGIN_DECL
 * \section pj_pstr_examples_sec Examples
 *
 * For some examples, please see:
- *  - @ref page_pjlib_string_test
+ *  - String test: \src{pjlib/src/pjlib-test/string.c}
 */

 /**
--- a/pjmedia/docs/doxygen.cfg
+++ b/pjmedia/docs/doxygen.cfg
@ -259,6 +259,10 @@ GENERATE_DEPRECATEDLIST= YES
 # You can put \n's in the value part of an alias to insert newlines.

 ALIASES                = 
+ALIASES               += src{1}="\verbatim embed:rst:inline :source:`\1` \endverbatim"
+ALIASES               += srcdir{1}="\verbatim embed:rst:inline :sourcedir:`\1` \endverbatim"
+ALIASES               += img{1}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" />"
+ALIASES               += img{2}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" alt=\"\2\" />"

 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
--- a/pjmedia/include/pjmedia/port.h
+++ b/pjmedia/include/pjmedia/port.h
@ -80,7 +80,7 @@
  of one WAV file to another. In this case, application would create and
  arrange media ports connection as follows:

-    \image html sample-manual-resampling.jpg
+  \img{pjmedia/docs/sample-manual-resampling.jpg}

  Application would setup the media ports using the following pseudo-
  code:
--- a/pjmedia/include/pjmedia/transport.h
+++ b/pjmedia/include/pjmedia/transport.h
@ -49,7 +49,7 @@
 * The connection between \ref PJMED_STRM and media transport is shown in
 * the diagram below:

-   \image html media-transport.PNG
+   \img{pjmedia/docs/media-transport.PNG}


 * \section PJMEDIA_TRANSPORT_H_USING Basic Media Transport Usage
--- a/pjmedia/include/pjmedia/transport_srtp.h
+++ b/pjmedia/include/pjmedia/transport_srtp.h
@ -44,7 +44,7 @@
 * media transport during stream creation), and the interconnection can be 
 * depicted from the diagram below:
 *
-   \image html media-transport.PNG
+   \img{pjmedia/docs/media-transport.PNG}

 * I think the diagram above is self-explanatory.
 *
@ -53,7 +53,7 @@
 * sending/receiving RTP/RTCP packets. When SRTP is used, the interconnection
 * between stream and transport is like the diagram below:
 *
-    \image html media-srtp-transport.PNG
+   \img{pjmedia/docs/media-srtp-transport.PNG}

 * So to stream, the SRTP transport behaves as if it is a media transport 
 * (because it is a media transport), and to the media transport it behaves
--- a/pjnath/docs/doc_ice.h
+++ b/pjnath/docs/doc_ice.h
@ -94,7 +94,7 @@ provides the best example on how to do this.

 \section ice_samples_sec Samples

-The \ref ice_demo_sample sample demonstrates how to use 
+The ICE demo sample \src{pjsip-apps/src/samples/icedemo.c} demonstrates how to use 
 \ref PJNATH_ICE_STREAM_TRANSPORT <b>without</b> using signaling 
 protocol such as <b>SIP</b>. It provides  interactive user interface
 to create and manage the ICE sessions as well as to exchange SDP 
--- a/pjnath/docs/doc_samples.h
+++ b/pjnath/docs/doc_samples.h
@ -25,26 +25,24 @@ below were taken on a Windows machine, but the library is very portable and
 it is known to run on platforms such as Linux, MacOS X, Windows Mobile,
 Symbian, and so on.

-  - @ref ice_demo_sample \n
+  - ICE demo sample: \src{pjsip-apps/src/samples/icedemo.c} <br />\n
    This sample demonstrates how to use \ref PJNATH_ICE_STREAM_TRANSPORT
    <b>without</b> using signaling protocol such as <b>SIP</b>. It provides 
    interactive user interface to create and manage the ICE sessions as well
-    as to exchange SDP with another ice_demo instance.\n\n
-    \image html ice_demo.jpg "ice_demo on WinXP"
+    as to exchange SDP with another ICE demo instance.\n\n
+    \img{pjnath/docs/ice_demo.jpg,ice_demo on WinXP}

-  - @ref turn_client_sample \n
+  - TURN client sample: \srcdir{pjnath/src/pjturn-client/} <br />\n
    This sample demonstrates how to use \ref PJNATH_TURN_SOCK
    and also \ref PJNATH_STUN_SOCK. It provides interactive 
    user interface to manage allocation, permissions, and
    channel bindings.\n\n
-    \image html pjturn_client.jpg "pjturn_client on WinXP"
+    \img{pjnath/docs/pjturn_client.jpg,pjturn_client on WinXP}

-  - TURN server sample \n
+  - TURN server sample: \srcdir{pjnath/src/pjturn-srv/} <br />\n
    This is a simple sample TURN server application, which
    we mainly use for testing (as back then there is no TURN
    server available).\n
-    The source code for this application are in <tt><b>pjnath/src/pjturn-srv</b></tt>
-    directory.

 */

--- a/pjnath/docs/doxygen.cfg
+++ b/pjnath/docs/doxygen.cfg
@ -259,6 +259,10 @@ GENERATE_DEPRECATEDLIST= YES
 # You can put \n's in the value part of an alias to insert newlines.

 ALIASES                = 
+ALIASES               += src{1}="\verbatim embed:rst:inline :source:`\1` \endverbatim"
+ALIASES               += srcdir{1}="\verbatim embed:rst:inline :sourcedir:`\1` \endverbatim"
+ALIASES               += img{1}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" />"
+ALIASES               += img{2}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" alt=\"\2\" />"

 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
--- a/pjsip/docs/doxygen.cfg
+++ b/pjsip/docs/doxygen.cfg
@ -260,6 +260,10 @@ GENERATE_DEPRECATEDLIST= YES
 # You can put \n's in the value part of an alias to insert newlines.

 ALIASES                = 
+ALIASES               += src{1}="\verbatim embed:rst:inline :source:`\1` \endverbatim"
+ALIASES               += srcdir{1}="\verbatim embed:rst:inline :sourcedir:`\1` \endverbatim"
+ALIASES               += img{1}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" />"
+ALIASES               += img{2}="<img src=\"https://raw.githubusercontent.com/pjsip/pjproject/master/\1\" alt=\"\2\" />"

 # The ENABLED_SECTIONS tag can be used to enable conditional 
 # documentation sections, marked by \if sectionname ... \endif.
--- a/pjsip/include/pjsua-lib/pjsua.h
+++ b/pjsip/include/pjsua-lib/pjsua.h
@ -90,11 +90,11 @@ PJ_BEGIN_DECL
 *
 * Few samples are provided:
 *
-  - @ref page_pjsip_sample_simple_pjsuaua_c \n
+  - Simple pjsua app: \src{pjsip-apps/src/samples/simple_pjsua.c} \n
    Very simple SIP User Agent with registration, call, and media, using
    PJSUA-API, all in under 200 lines of code.

-  - @ref page_pjsip_samples_pjsua \n
+  - Pjsua app: \srcdir{pjsip-apps/src/pjsua/} \n
    This is the reference implementation for PJSIP and PJMEDIA.
    PJSUA is a console based application, designed to be simple enough
    to be readble, but powerful enough to demonstrate all features