Fixed typos in doc + improved javadoc

include/linphone/api/c-types.h

@@ -90,7 +90,7 @@ typedef struct _LinphoneAuthInfo LinphoneAuthInfo;
  * A SIP address is made of display name, username, domain name, port, and various
  * uri headers (such as tags). It looks like 'Alice <sip:alice@example.net>'.
  * 
- * You can create an address using linphone_factory_create_address() or linphone_core_interpret_url(),
+ * You can create an address using linphone_factory_create_address() or linphone_core_interpret_url()
  * and both will return a NULL object if it doesn't match the grammar defined by the standard.
  * 
  * This object is used in almost every other major objects to identity people (including yourself) & servers.
@@ -133,7 +133,7 @@ typedef struct _LinphoneConferenceCbs LinphoneConferenceCbs;
  * @brief Identifies a member of a #LinphoneConference or #LinphoneChatRoom.
  * 
  * A participant is identified by it's SIP address.
- * It can have many devices, @see #LinphoneParticipantDevice.
+ * It can have many #LinphoneParticipantDevice.
  * @ingroup conference
  */
 typedef struct _LinphoneParticipant LinphoneParticipant;
@@ -161,7 +161,7 @@ typedef struct _LinphoneParticipantDevice LinphoneParticipantDevice;
 typedef struct _LinphoneParticipantImdnState LinphoneParticipantImdnState;
 
 /**
- * @brief This object is only used on server side for group chat rooms.
+ * @brief This object is only used on server side for #LinphoneChatRoom with #LinphoneChatRoomBackendFlexisipChat backend.
  * @ingroup conference
  */
 typedef struct _LinphoneParticipantDeviceIdentity LinphoneParticipantDeviceIdentity;
@@ -264,7 +264,7 @@ typedef struct _LinphoneAudioDevice LinphoneAudioDevice;
  * On the receiving side, either use linphone_chat_message_download_content() to download received files or enable auto-download in the #LinphoneCore using 
  * linphone_core_set_max_size_for_auto_download_incoming_files(), -1 disabling the feature and 0 always downloading files no matter it's size.
  * 
- * Keep in mind a #LinphoneChatMessage created by a 'Basic' #LinphoneChatRoom can only contain one #LinphoneContent, either text or file.
+ * Keep in mind a #LinphoneChatMessage created by a #LinphoneChatRoomBackendBasic #LinphoneChatRoom can only contain one #LinphoneContent, either text or file.
  * @ingroup chatroom
  */
 typedef struct _LinphoneChatMessage LinphoneChatMessage;
@@ -280,10 +280,10 @@ typedef struct _LinphoneChatMessageCbs LinphoneChatMessageCbs;
  * 
  * To create (or find) a #LinphoneChatRoom, you first need a #LinphoneChatRoomParams object.
  * A chat room is uniquely identified by it's local and remote SIP addresses, meaning you can
- * only have one chat room between two accounts (unless the backend is 'Flexisip').
+ * only have one chat room between two accounts (unless the backend is #LinphoneChatRoomBackendFlexisipChat).
  * Then you can call linphone_core_search_chat_room() or linphone_core_create_chat_room_6().
  * 
- * Be careful as a 'Flexisip' backend #LinphoneChatRoom will be created asynchronously, so
+ * Be careful as a #LinphoneChatRoomBackendFlexisipChat backend #LinphoneChatRoom will be created asynchronously, so
  * make sure you add a #LinphoneChatRoomCbs to the returned object to be notified 
  * when it will be in state #LinphoneChatRoomStateCreated.
  * 
@@ -301,8 +301,8 @@ typedef struct _LinphoneChatRoom LinphoneChatRoom;
  * Can be created with linphone_core_create_default_chat_room_params().
  * You can use linphone_chat_room_params_is_valid() to check if your configuration is valid or not.
  * 
- * If the #LinphoneChatRoom backend is 'Basic', then no other parameter is required, 
- * but #LinphoneChatMessage sent and received won't benefit from all features a 'FlexisipBackend' can offer 
+ * If the #LinphoneChatRoom backend is #LinphoneChatRoomBackendBasic, then no other parameter is required, 
+ * but #LinphoneChatMessage sent and received won't benefit from all features a #LinphoneChatRoomBackendFlexisipChat can offer 
  * like conversation with multiple participants and a subject, end-to-end encryption, ephemeral messages, etc... 
  * but this type is the only one that can interoperate with other SIP clients or with non-flexisip SIP proxies.
  * @ingroup chatroom

include/linphone/call_log.h

@@ -207,7 +207,7 @@ LINPHONE_PUBLIC LinphoneCallLog * linphone_call_log_ref(LinphoneCallLog *call_lo
 LINPHONE_PUBLIC void linphone_call_log_unref(LinphoneCallLog *call_log);
 
 /**
- * Creates a fake LinphoneCallLog.
+ * Creates a fake #LinphoneCallLog.
  * @param core #LinphoneCore object @notnil
  * @param from #LinphoneAddress of caller @notnil
  * @param to #LinphoneAddress of callee @notnil

include/linphone/factory.h

@@ -62,7 +62,7 @@ LINPHONE_PUBLIC void linphone_factory_clean(void);
  * @param system_context A pointer to a system object required by the core to operate. Currently it is required to
  * pass an android Context on android, pass NULL on other platforms. @maybenil
  * @return a #LinphoneCore object @notnil
- * @see linphone_core_new_with_config_3
+ * @see linphone_core_new_with_config_3()
  */
 LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_3 (
 	const LinphoneFactory *factory,
@@ -101,7 +101,7 @@ LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_3 (
  * @param app_group_id Name of iOS App Group that lead to the file system that is shared between an app and its app extensions. @notnil
  * @param main_core Indicate if we want to create a "Main Core" or an "Executor Core".
  * @return a #LinphoneCore object @notnil
- * @see linphone_factory_create_shared_core_with_config
+ * @see linphone_factory_create_shared_core_with_config()
  */
 LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_shared_core (
 	const LinphoneFactory *factory,
@@ -125,7 +125,7 @@ LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_shared_core (
  * @param system_context A pointer to a system object required by the core to operate. Currently it is required to
  * pass an android Context on android, pass NULL on other platforms. @maybenil
  * @return a #LinphoneCore object @notnil
- * @see linphone_factory_create_core_3
+ * @see linphone_factory_create_core_3()
  */
 LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config_3 (
 	const LinphoneFactory *factory,
@@ -157,7 +157,7 @@ LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_with_config_3 (
  * @param app_group_id Name of iOS App Group that lead to the file system that is shared between an app and its app extensions. @notnil
  * @param main_core Indicate if we want to create a "Main Core" or an "Executor Core".
  * @return a #LinphoneCore object @notnil
- * @see linphone_factory_create_shared_core
+ * @see linphone_factory_create_shared_core()
  */
 LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_shared_core_with_config (
 	const LinphoneFactory *factory,
@@ -613,7 +613,7 @@ LINPHONE_PUBLIC const char *linphone_factory_get_download_dir(LinphoneFactory *f
  *        to store hard-coded preference such as proxy settings or internal preferences.
  *        The settings in this factory file always override the one in the normal config file.
  *        It is OPTIONAL, use NULL if unneeded.
- * @see linphone_core_new_with_config
+ * @see linphone_core_new_with_config()
  * @deprecated 2018-01-10: Use linphone_factory_create_core_3() instead
  * @donotwrap
  */
@@ -643,7 +643,7 @@ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core(
  *        It is OPTIONAL, use NULL if unneeded.
  * @param user_data an application pointer associated with the returned core.
  * @param system_context a pointer to a system object required by the core to operate. Currently it is required to pass an android Context on android, pass NULL on other platforms.
- * @see linphone_core_new_with_config
+ * @see linphone_core_new_with_config()
  * @deprecated 2018-01-10: Use linphone_factory_create_core_3() instead
  * @donotwrap
  */
@@ -666,7 +666,7 @@ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_2
  * will be taken on it until the destruciton of the core or the unregistration
  * with linphone_core_remove_cbs().
  * @param config a pointer to an LpConfig object holding the configuration of the #LinphoneCore to be instantiated.
- * @see linphone_core_new
+ * @see linphone_core_new()
  * @deprecated 2018-01-10: Use linphone_factory_create_core_with_config_3() instead
  * @donotwrap
  */
@@ -688,7 +688,7 @@ LINPHONE_DEPRECATED LINPHONE_PUBLIC LinphoneCore *linphone_factory_create_core_w
  * @param config a pointer to an LpConfig object holding the configuration of the #LinphoneCore to be instantiated.
  * @param user_data an application pointer associated with the returned core.
  * @param system_context a pointer to a system object required by the core to operate. Currently it is required to pass an android Context on android, pass NULL on other platforms.
- * @see linphone_core_new
+ * @see linphone_core_new()
  * @deprecated 2018-01-10: Use linphone_factory_create_core_with_config_3() instead
  * @donotwrap
  */

include/linphone/logging.h

@@ -38,7 +38,7 @@ extern "C" {
  * It supports custom domain, writing into a file as well as several verbosity levels.
  * The #LinphoneLoggingServiceCbs listener allows you to be notified each time a log is printed.
  * 
- * As the #LoggingService is a singleton, use linphone_logging_service_get() to get it.
+ * As the #LinphoneLoggingService is a singleton, use linphone_logging_service_get() to get it.
  */
 typedef struct _LinphoneLoggingService LinphoneLoggingService;
 

include/linphone/types.h

@@ -52,9 +52,8 @@
 typedef struct _LinphoneProxyConfig LinphoneProxyConfig;
 
 /**
- * @brief The object used to configure an account on a server via XML-RPC.
- * 
- * @see https://wiki.linphone.org/xwiki/wiki/public/view/Lib/Features/Override%20account%20creator%20request/
+ * @brief The object used to configure an account on a server via XML-RPC, 
+ * see @link https://wiki.linphone.org/xwiki/wiki/public/view/Lib/Features/Override%20account%20creator%20request/
  * @ingroup account_creator
 **/
 typedef struct _LinphoneAccountCreator LinphoneAccountCreator;
@@ -271,10 +270,10 @@ typedef struct _LinphoneFriend LinphoneFriend;
 * @ingroup buddy_list
 **/
 typedef enum _LinphoneFriendCapability {
-	LinphoneFriendCapabilityNone = 0, /** No capabilities populated */
-	LinphoneFriendCapabilityGroupChat = 1 << 0, /** This friend can be invited in a Flexisip backend #LinphoneChatRoom */
-	LinphoneFriendCapabilityLimeX3dh = 1 << 1, /** This friend can be invited in a Flexisip backend end-to-end encrypted #LinphoneChatRoom */
-	LinphoneFriendCapabilityEphemeralMessages = 1 << 2 /** This friend is able to delete ephemeral messages once they have expired */
+	LinphoneFriendCapabilityNone = 0, /**< No capabilities populated */
+	LinphoneFriendCapabilityGroupChat = 1 << 0, /**< This friend can be invited in a Flexisip backend #LinphoneChatRoom */
+	LinphoneFriendCapabilityLimeX3dh = 1 << 1, /**< This friend can be invited in a Flexisip backend end-to-end encrypted #LinphoneChatRoom */
+	LinphoneFriendCapabilityEphemeralMessages = 1 << 2 /**< This friend is able to delete ephemeral messages once they have expired */
 } LinphoneFriendCapability;
 
 /**
@@ -296,9 +295,9 @@ typedef struct _LinphoneFriendListCbs LinphoneFriendListCbs;
 * @ingroup buddy_list
 **/
 typedef enum _LinphoneFriendListStatus {
-	LinphoneFriendListOK, /** Operation went fine */
-	LinphoneFriendListNonExistentFriend, /** #LinphoneFriend wasn't found in the #LinphoneFriendList */
-	LinphoneFriendListInvalidFriend /** #LinphoneFriend is already present in a #LinphoneFriendList */
+	LinphoneFriendListOK, /**< Operation went fine */
+	LinphoneFriendListNonExistentFriend, /**< #LinphoneFriend wasn't found in the #LinphoneFriendList */
+	LinphoneFriendListInvalidFriend /**< #LinphoneFriend is already present in a #LinphoneFriendList */
 } LinphoneFriendListStatus;
 
 /**
@@ -306,9 +305,9 @@ typedef enum _LinphoneFriendListStatus {
  * @ingroup buddy_list
  */
 typedef enum _LinphoneFriendListSyncStatus {
-	LinphoneFriendListSyncStarted, /** Synchronization started */
-	LinphoneFriendListSyncSuccessful, /** Synchronization finished successfuly */
-	LinphoneFriendListSyncFailure /** Synchronization failed */
+	LinphoneFriendListSyncStarted, /**< Synchronization started */
+	LinphoneFriendListSyncSuccessful, /**< Synchronization finished successfuly */
+	LinphoneFriendListSyncFailure /**< Synchronization failed */
 } LinphoneFriendListSyncStatus;
 
 // -----------------------------------------------------------------------------
@@ -389,7 +388,7 @@ typedef enum _LinphoneRegistrationState {
  * @brief Main object to instanciate and on which to keep a reference.
  * 
  * This object is the first object to instanciante, and will allow you to perform all kind of tasks.
- * To create it, use either #linphone_factory_create_core3() or linphone_factory_create_core_with_config_3(),
+ * To create it, use either linphone_factory_create_core_3() or linphone_factory_create_core_with_config_3(),
  * see #LinphoneConfig for more information about factory and default config.
  * On some platforms like Android or iOS you will need to give it the Context of your application.
  * 
@@ -1134,7 +1133,7 @@ typedef enum _LinphoneUpnpState {
 } LinphoneUpnpState;
 
 /**
- * @brief The #LinphoneVcard object.
+ * @brief Object storing contact information using vCard 4.0 format.
  * @ingroup carddav_vcard
  */
 typedef struct _LinphoneVcard LinphoneVcard;

tools/metadoc.py

@@ -499,10 +499,15 @@ class Translator:
 		while len(line) > width:
 			cutIndex = line.rfind(' ', 0, width)
 			if cutIndex != -1:
+				if self.langCode == 'Java':
+					# Do not break a line in the middle of a { }
+					while (not line[0:cutIndex].count('{') == line[0:cutIndex].count('}')) and (not line[cutIndex:].count('{') == line[cutIndex:].count('}')):
+						cutIndex += 1
 				lines.append(line[0:cutIndex])
 				line = line[cutIndex+1:]
 			else:
-				cutIndex = width
+				# Don't break http links
+				cutIndex = len(line) if ('http://' or 'https://') in line else width
 				lines.append(line[0:cutIndex])
 				line = line[cutIndex:]
 		lines.append(line)
@@ -557,17 +562,17 @@ class JavaDocTranslator(DoxygenTranslator):
 		pass
 
 	def translate_class_reference(self, ref, **kargs):
-		if not isinstance(ref.relatedObject, (abstractapi.Class, abstractapi.Enum)):
+		if not isinstance(ref.relatedObject, (abstractapi.Class, abstractapi.Enum, abstractapi.Interface)):
 			raise ReferenceTranslationError(ref.cname)
 		return '{@link ' + Translator.translate_reference(self, ref) + '}'
 	
 	def _translate_section(self, section):
 		if section.kind == 'see':
-			return 'See also: {0}'.format(self._translate_paragraph(section.paragraph))
+			return 'see: {0}'.format(self._translate_paragraph(section.paragraph))
 		if section.kind == 'note':
-			return 'Note: {0}'.format(self._translate_paragraph(section.paragraph))
+			return 'note: {0}'.format(self._translate_paragraph(section.paragraph))
 		if section.kind == 'warning':
-			return 'Warning: {0}'.format(self._translate_paragraph(section.paragraph))
+			return 'warning: {0}'.format(self._translate_paragraph(section.paragraph))
 			
 		return '@{0} {1}'.format(
 			section.kind,
@@ -582,6 +587,15 @@ class JavaDocTranslator(DoxygenTranslator):
 		methodName = ref.relatedObject.name.translate(self.nameTranslator)
 		return '{@link ' + className + '#' + methodName + '}'
 
+	def _translate_parameter_list(self, parameterList):
+		text = ''
+		for paramDesc in parameterList.parameters:
+			if self.displaySelfParam or not paramDesc.is_self_parameter():
+				desc = self._translate_description(paramDesc.desc)
+				desc = desc[0] if len(desc) > 0 else ''
+				text += ('@param {0} {1}\n'.format(paramDesc.name.translate(self.nameTranslator), desc))
+		return text
+
 
 class SwiftDocTranslator(JavaDocTranslator):
 	def __init__(self):

wrappers/java/java_class.mustache

@@ -40,13 +40,13 @@ import org.linphone.mediastream.Version;
 /**
 {{#briefDoc}}
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/briefDoc}}
 {{#detailedDoc}}
-*
+* <br/>
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/detailedDoc}}
 */
@@ -57,13 +57,13 @@ public {{#isLinphoneFactory}}abstract class{{/isLinphoneFactory}}{{#isNotLinphon
         /**
         {{#briefDoc}}
         {{#lines}}
-        * {{{line}}}
+        * {{{line}}}<br/>
         {{/lines}}
         {{/briefDoc}}
         {{#detailedDoc}}
-        *
+        * <br/>
         {{#lines}}
-        * {{{line}}}
+        * {{{line}}}<br/>
         {{/lines}}
         {{/detailedDoc}}
         */
@@ -126,13 +126,13 @@ public {{#isLinphoneFactory}}abstract class{{/isLinphoneFactory}}{{#isNotLinphon
     /**
     {{#briefDoc}}
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/briefDoc}}
     {{#detailedDoc}}
-    *
+    * <br/>
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/detailedDoc}}
     */

wrappers/java/java_enum.mustache

@@ -28,13 +28,13 @@ import {{import}}
 /**
 {{#briefDoc}}
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/briefDoc}}
 {{#detailedDoc}}
-*
+* <br/>
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/detailedDoc}}
 */
@@ -43,13 +43,13 @@ public enum {{{className}}} {
     /**
     {{#briefDoc}}
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/briefDoc}}
     {{#detailedDoc}}
-    *
+    * <br/>
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/detailedDoc}}
     */

wrappers/java/java_enum_old.mustache

@@ -26,13 +26,13 @@ import {{import}}
 /**
 {{#briefDoc}}
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/briefDoc}}
-*
+* <br/>
 {{#detailedDoc}}
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/detailedDoc}}
 */
@@ -43,13 +43,13 @@ static public class {{className}} {
     /**
     {{#briefDoc}}
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/briefDoc}}
-    *
+    * <br/>
     {{#detailedDoc}}
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/detailedDoc}}
     */

wrappers/java/java_interface.mustache

@@ -28,13 +28,13 @@ import {{import}}
 /**
 {{#briefDoc}}
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/briefDoc}}
 {{#detailedDoc}}
-*
+* <br/>
 {{#lines}}
-* {{{line}}}
+* {{{line}}}<br/>
 {{/lines}}
 {{/detailedDoc}}
 */
@@ -43,13 +43,13 @@ public interface {{className}} {
     /**
     {{#briefDoc}}
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/briefDoc}}
     {{#detailedDoc}}
-    *
+    * <br/>
     {{#lines}}
-    * {{{line}}}
+    * {{{line}}}<br/>
     {{/lines}}
     {{/detailedDoc}}
     */

wrappers/java/package_info.mustache

 /**
- * <a href="http://www.linphone.org">Liblinphone</a> is a high-level open source library that integrates all the SIP voice/video and instant messaging features into a single easy-to-use API.</br>
- * This is the VoIP SDK engine on which Linphone applications are based.</br>
- * </br>
- * Liblinphone combines our media processing and streaming toolkit (Mediastreamer2) with our user-agent library for SIP signaling (belle-sip).</br>
- * Liblinphone has support for a variety of languages, each one has its own reference documentation:</br>
+ * <a href="http://www.linphone.org">Liblinphone</a> is a high-level open source library that integrates all the SIP voice/video and instant messaging features into a single easy-to-use API.<br/>
+ * This is the VoIP SDK engine on which Linphone applications are based.<br/>
+ * <br/>
+ * Liblinphone combines our media processing and streaming toolkit (Mediastreamer2) with our user-agent library for SIP signaling (belle-sip).<br/>
+ * Liblinphone has support for a variety of languages, each one has its own reference documentation:<br/>
  * <ul>
  * <li><a href="https://linphone.org/{{directory}}/docs/liblinphone/{{version}}/c">C</a></li>
  * <li><a href="https://linphone.org/{{directory}}/docs/liblinphone/{{version}}/c++">C++</a></li>
@@ -12,8 +12,8 @@
  * <li>C# (coming soon)</li>
  * <li>Python (coming soon)</li>
  * </ul>
- * Liblinphone is distributed under <a href="https://www.gnu.org/licenses/gpl-3.0.html">GPLv3</a>. Please understand the licencing details before using it!</br>
- * </br>
- * For any use of this library beyond the rights granted to you by the GPLv3 license, please <a href="https://www.linphone.org/contact">contact Belledonne Communications</a>.</br>
+ * Liblinphone is distributed under <a href="https://www.gnu.org/licenses/gpl-3.0.html">GPLv3</a>. Please understand the licencing details before using it!<br/>
+ * <br/>
+ * For any use of this library beyond the rights granted to you by the GPLv3 license, please <a href="https://www.linphone.org/contact">contact Belledonne Communications</a>.<br/>
  */
 package org.linphone.core;
\ No newline at end of file