Add documentation to ClientDotNet and LogDotNet.

GitOrigin-RevId: 4683cfb7198430314539780fa793898ff6c36e96

CMakeLists.txt

@@ -627,6 +627,7 @@ if (TD_ENABLE_DOTNET)
   if (NOT CMAKE_CROSSCOMPILING)
     add_dependencies(tddotnet generate_dotnet_api)
   endif()
+
   if ("${CMAKE_SYSTEM_NAME}" STREQUAL "WindowsStore")
     set_target_properties(tddotnet PROPERTIES VS_WINRT_COMPONENT "true")
     target_compile_options(tddotnet PUBLIC "/ZW")

example/java/org/drinkless/tdlib/Log.java

@@ -31,7 +31,7 @@ public final class Log {
      *
      * @param filePath Path to a file for writing TDLib internal log. Use an empty path to
      *                 switch back to logging to the System.err.
-     * @return whether opening the log file succeeded
+     * @return whether opening the log file succeeded.
      */
     public static native boolean setFilePath(String filePath);
 

td/generate/CMakeLists.txt

@@ -87,7 +87,7 @@ set(TL_GENERATE_JSON_SOURCE
 if (NOT CMAKE_CROSSCOMPILING)
   find_program(PHP_EXECUTABLE php)
 
-  if (PHP_EXECUTABLE)
+  if (PHP_EXECUTABLE AND NOT TD_ENABLE_DOTNET)
     set(GENERATE_COMMON_CMD generate_common && ${PHP_EXECUTABLE} DoxygenTlDocumentationGenerator.php scheme/td_api.tl auto/td/telegram/td_api.h)
   else()
     set(GENERATE_COMMON_CMD generate_common)

td/generate/generate_dotnet.cpp

@@ -17,7 +17,7 @@ int main(int argc, char *argv[]) {
   td::tl::tl_config config_td = td::tl::read_tl_config_from_file(argv[1]);
 
   td::tl::write_tl_to_file(config_td, "auto/td/telegram/TdDotNetApi.cpp",
-                           td::tl::TlWriterDotNet("TdApi", false, "#include \"td/telegram/TdDotNetApi.h\"\n"));
+                           td::tl::TlWriterDotNet("TdApi", false, "#include \"td/telegram/TdDotNetApi.h\"\n\n"));
   td::tl::write_tl_to_file(config_td, "auto/td/telegram/TdDotNetApi.h",
-                           td::tl::TlWriterDotNet("TdApi", true, "#include \"td/telegram/td_api.h\"\n"));
+                           td::tl::TlWriterDotNet("TdApi", true, ""));
 }

td/generate/tl_writer_dotnet.h

@@ -179,7 +179,6 @@ class TlWriterDotNet : public TL_writer {
   }
   std::string gen_output_begin(void) const override {
     return prefix_ +
-           "#include \"td/utils/port/CxCli.h\"\n"
            "#include \"td/tl/tl_dotnet_object.h\"\n\n"
            "namespace Telegram {\n"
            "namespace Td {\n"

td/telegram/ClientDotNet.cpp

@@ -4,10 +4,10 @@
 // Distributed under the Boost Software License, Version 1.0. (See accompanying
 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 //
-#include "td/telegram/TdDotNetApi.h"
-
 #include "td/telegram/Client.h"
 
+#include "td/telegram/TdDotNetApi.h"
+
 #include "td/utils/port/CxCli.h"
 
 #include <cstdint>
@@ -17,12 +17,29 @@ namespace Td {
 
 using namespace CxCli;
 
+/// <summary>
+/// Interface for handler for results of queries to TDLib and incoming updates from TDLib.
+/// </summary>
 public interface class ClientResultHandler {
+  /// <summary>
+  /// Callback called on result of query to TDLib or incoming update from TDLib.
+  /// </summary>
+  /// <param name="object">Result of query or update of type Telegram.Td.Api.Update about new events.</param>
   void OnResult(Api::BaseObject^ object);
 };
 
+/// <summary>
+/// Main class for interaction with the TDLib.
+/// </summary>
 public ref class Client sealed {
 public:
+  /// <summary>
+  /// Sends a request to the TDLib.
+  /// </summary>
+  /// <param name="function">Object representing a query to the TDLib.</param>
+  /// <param name="handler">Result handler with OnResult method which will be called with result
+  /// of the query or with Telegram.Td.Api.Error as parameter. If it is null, nothing will be called.</param>
+  /// <exception cref="NullReferenceException">Thrown when query is null.</exception>
   void Send(Api::Function^ function, ClientResultHandler^ handler) {
     if (function == nullptr) {
       throw REF_NEW NullReferenceException("Function can't be null");
@@ -38,6 +55,12 @@ public:
     client->send(std::move(request));
   }
 
+  /// <summary>
+  /// Synchronously executes a TDLib request. Only a few marked accordingly requests can be executed synchronously.
+  /// </summary>
+  /// <param name="function">Object representing a query to the TDLib.</param>
+  /// <returns>Returns request result.</returns>
+  /// <exception cref="NullReferenceException">Thrown when query is null.</exception>
   Api::BaseObject^ Execute(Api::Function^ function) {
     if (function == nullptr) {
       throw REF_NEW NullReferenceException("Function can't be null");
@@ -49,10 +72,19 @@ public:
     return Api::FromUnmanaged(*client->execute(std::move(request)).object);
   }
 
-  void SetUpdatesHandler(ClientResultHandler^ handler) {
+  /// <summary>
-    handlers[0] = handler;
+  /// Replaces handler for incoming updates from the TDLib.
+  /// </summary>
+  /// <param name="updatesHandler">Handler with OnResult method which will be called for every incoming update from the TDLib.</param>
+  void SetUpdatesHandler(ClientResultHandler^ updatesHandler) {
+    handlers[0] = updatesHandler;
   }
 
+  /// <summary>
+  /// Launches a cycle which will fetch all results of queries to TDLib and incoming updates from TDLib.
+  /// Must be called once on a separate dedicated thread, on which all updates and query results will be handled.
+  /// Returns only when TDLib instance is closed.
+  /// </summary>
   void Run() {
     while (true) {
       auto response = client->receive(10.0);
@@ -68,6 +100,11 @@ public:
     }
   }
 
+  /// <summary>
+  /// Creates new Client.
+  /// </summary>
+  /// <param name="updatesHandler">Handler for incoming updates.</param>
+  /// <returns>Returns created Client.</returns>
   static Client^ Create(ClientResultHandler^ updatesHandler) {
     return REF_NEW Client(updatesHandler);
   }

td/telegram/LogDotNet.cpp

@@ -15,19 +15,41 @@ namespace Td {
 
 using namespace CxCli;
 
+/// <summary>
+/// Class for managing internal TDLib logging.
+/// </summary>
 public ref class Log sealed {
 public:
+  /// <summary>
+  /// Changes TDLib log verbosity.
+  /// </summary>
+  /// <param name="verbosityLevel">New value of log verbosity level. Must be non-negative.
+  /// Value 0 means FATAL, value 1 means ERROR, value 2 means WARNING, value 3 means INFO, value 4 means DEBUG,
+  /// value greater than 4 can be used to enable even more logging.
+  /// Default value of the log verbosity level is 5.</param>
+  static void SetVerbosityLevel(int verbosityLevel) {
+    ::td::Log::set_verbosity_level(verbosityLevel);
+  }
+
+  /// <summary>
+  /// Sets file path for writing TDLib internal log. By default TDLib writes logs to the System.err.
+  /// Use this method to write the log to a file instead.
+  /// </summary>
+  /// <param name="filePath">Path to a file for writing TDLib internal log. Use an empty path to switch back to logging
+  /// to the System.err.</param>
+  /// <returns>Returns whether opening the log file succeeded.</returns>
   static bool SetFilePath(String^ filePath) {
     return ::td::Log::set_file_path(string_to_unmanaged(filePath));
   }
 
+  /// <summary>
+  /// Changes maximum size of TDLib log file.
+  /// </summary>
+  /// <param name="maxFileSize">Maximum size of the file to where the internal TDLib log is written
+  /// before the file will be auto-rotated. Must be positive. Defaults to 10 MB.</param>
   static void SetMaxFileSize(std::int64_t maxFileSize) {
     ::td::Log::set_max_file_size(maxFileSize);
   }
-
-  static void SetVerbosityLevel(int verbosityLevel) {
-    ::td::Log::set_verbosity_level(verbosityLevel);
-  }
 };
 
 }  // namespace Td

td/tl/tl_dotnet_object.h

@@ -6,7 +6,6 @@
 //
 #pragma once
 
-#include "td/utils/misc.h"
 #include "td/utils/port/CxCli.h"
 
 #include "td/telegram/td_api.h"
@@ -64,7 +63,7 @@ inline String^ FromUnmanaged(const std::string &from) {
 }
 
 inline auto CLRCALL BytesFromUnmanaged(const std::string &from) {
-  Array<byte>^ res = REF_NEW Vector<byte>(td::narrow_cast<int>(from.size()));
+  Array<byte>^ res = REF_NEW Vector<byte>(static_cast<ArrayIndexType>(from.size()));
   ArrayIndexType i = 0;
   for (auto b : from) {
     ArraySet(res, i++, b);
@@ -75,7 +74,7 @@ inline auto CLRCALL BytesFromUnmanaged(const std::string &from) {
 template <class FromT>
 auto CLRCALL FromUnmanaged(std::vector<FromT> &vec) {
   using ToT = decltype(FromUnmanaged(vec[0]));
-  Array<ToT>^ res = REF_NEW Vector<ToT>(td::narrow_cast<int>(vec.size()));
+  Array<ToT>^ res = REF_NEW Vector<ToT>(static_cast<ArrayIndexType>(vec.size()));
   ArrayIndexType i = 0;
   for (auto &from : vec) {
     ArraySet(res, i++, FromUnmanaged(from));

tdutils/td/utils/port/CxCli.h

@@ -13,7 +13,6 @@
 
 #if TD_WINRT
 
-#include "td/utils/misc.h"  // for narrow_cast
 #include "td/utils/port/wstring_convert.h"
 
 #include "collection.h"
@@ -83,7 +82,7 @@ inline std::string string_to_unmanaged(String^ str) {
 
 inline String^ string_from_unmanaged(const std::string &from) {
   auto tmp = td::to_wstring(from).ok();
-  return REF_NEW String(tmp.c_str(), td::narrow_cast<unsigned>(tmp.size()));
+  return REF_NEW String(tmp.c_str(), static_cast<unsigned>(tmp.size()));
 }
 
 } // namespace CxCli