Improve the jerry port api documents. (#4977)

Notable changes:
  - Remove the comments in port impl, that's easily getting to in-consistence
  - Sync the jerryscript-port.h and 05.PORT-API.md
  - Fixes the invalid comment in port codes

JerryScript-DCO-1.0-Signed-off-by: Yonggang Luo luoyonggang@gmail.com

docs/05.PORT-API.md

@@ -119,6 +119,8 @@ void jerry_port_context_free (void);
  *
  * The implementation can decide whether error and debug messages are logged to
  * the console, or saved to a database or to a file.
+ *
+ * @param message_p: the message to log.
  */
 void jerry_port_log (const char *message_p);
 ```

jerry-core/include/jerryscript-port.h

@@ -143,6 +143,8 @@ void jerry_port_context_free (void);
  *
  * The implementation can decide whether error and debug messages are logged to
  * the console, or saved to a database or to a file.
+ *
+ * @param message_p: the message to log.
  */
 void jerry_port_log (const char *message_p);
 
@@ -237,7 +239,7 @@ void jerry_port_path_free (jerry_char_t *path_p);
 jerry_size_t jerry_port_path_base (const jerry_char_t *path_p);
 
 /**
- * Open a source file and read the content into a buffer.
+ * Open a source file and read its contents into a buffer.
  *
  * When the source file is no longer needed by the caller, the returned pointer will be passed to
  * `jerry_port_source_free`, which can be used to finalize the buffer.

jerry-port/common/jerry-port-context.c

@@ -27,13 +27,6 @@
  */
 static jerry_context_t *current_context_p = NULL;
 
-/**
- * Allocate a new external context.
- *
- * @param context_size: requested context size
- *
- * @return total allcoated size
- */
 size_t JERRY_ATTR_WEAK
 jerry_port_context_alloc (size_t context_size)
 {
@@ -43,20 +36,12 @@ jerry_port_context_alloc (size_t context_size)
   return total_size;
 } /* jerry_port_context_alloc */
 
-/**
- * Get the current context.
- *
- * @return the pointer to the current context
- */
 jerry_context_t *JERRY_ATTR_WEAK
 jerry_port_context_get (void)
 {
   return current_context_p;
 } /* jerry_port_context_get */
 
-/**
- * Free the currently allocated external context.
- */
 void JERRY_ATTR_WEAK
 jerry_port_context_free (void)
 {

jerry-port/common/jerry-port-fs.c

@@ -41,13 +41,8 @@ jerry_port_get_file_size (FILE *file_p) /**< opened file */
   return (jerry_size_t) size;
 } /* jerry_port_get_file_size */
 
-/**
- * Opens file with the given path and reads its source.
- * @return the source of the file
- */
 jerry_char_t *JERRY_ATTR_WEAK
-jerry_port_source_read (const char *file_name_p, /**< file name */
+jerry_port_source_read (const char *file_name_p, jerry_size_t *out_size_p)
-                        jerry_size_t *out_size_p) /**< [out] read bytes */
 {
   /* TODO(dbatyai): Temporary workaround for nuttx target
    * The nuttx target builds and copies the jerryscript libraries as a separate build step, which causes linking issues
@@ -92,11 +87,8 @@ jerry_port_source_read (const char *file_name_p, /**< file name */
   return buffer_p;
 } /* jerry_port_source_read */
 
-/**
- * Release the previously opened file's content.
- */
 void JERRY_ATTR_WEAK
-jerry_port_source_free (uint8_t *buffer_p) /**< buffer to free */
+jerry_port_source_free (uint8_t *buffer_p)
 {
   free (buffer_p);
 } /* jerry_port_source_free */
@@ -107,15 +99,8 @@ jerry_port_source_free (uint8_t *buffer_p) /**< buffer to free */
  */
 #if defined(JERRY_WEAK_SYMBOL_SUPPORT) && !(defined(__unix__) || defined(__APPLE__) || defined(_WIN32))
 
-/**
- * Normalize a file path.
- *
- * @return a newly allocated buffer with the normalized path if the operation is successful,
- *         NULL otherwise
- */
 jerry_char_t *JERRY_ATTR_WEAK
-jerry_port_path_normalize (const jerry_char_t *path_p, /**< input path */
+jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size)
-                           jerry_size_t path_size) /**< size of the path */
 {
   jerry_char_t *buffer_p = (jerry_char_t *) malloc (path_size + 1);
 
@@ -130,24 +115,14 @@ jerry_port_path_normalize (const jerry_char_t *path_p, /**< input path */
   return buffer_p;
 } /* jerry_port_path_normalize */
 
-/**
- * Free a path buffer returned by jerry_port_path_normalize.
- *
- * @param path_p: the path to free
- */
 void JERRY_ATTR_WEAK
 jerry_port_path_free (jerry_char_t *path_p)
 {
   free (path_p);
 } /* jerry_port_path_free */
 
-/**
- * Computes the end of the directory part of a path.
- *
- * @return end of the directory part of a path.
- */
 jerry_size_t JERRY_ATTR_WEAK
-jerry_port_path_base (const jerry_char_t *path_p) /**< path */
+jerry_port_path_base (const jerry_char_t *path_p)
 {
   const jerry_char_t *basename_p = (jerry_char_t *) strrchr ((char *) path_p, '/') + 1;
 
@@ -157,6 +132,6 @@ jerry_port_path_base (const jerry_char_t *path_p) /**< path */
   }
 
   return (jerry_size_t) (basename_p - path_p);
-} /* jerry_port_get_directory_end */
+} /* jerry_port_path_base */
 
 #endif /* defined(JERRY_WEAK_SYMBOL_SUPPORT) && !(defined(__unix__) || defined(__APPLE__) || defined(_WIN32)) */

jerry-port/common/jerry-port-io.c

@@ -34,14 +34,6 @@ jerry_port_print_buffer (const jerry_char_t *buffer_p, jerry_size_t buffer_size)
   fwrite (buffer_p, 1, buffer_size, stdout);
 } /* jerry_port_print_buffer */
 
-/**
- * Read a line from standard input as a zero-terminated string.
- *
- * @param out_size_p: length of the string
- *
- * @return pointer to the buffer storing the string,
- *         or NULL if end of input
- */
 jerry_char_t *JERRY_ATTR_WEAK
 jerry_port_line_read (jerry_size_t *out_size_p)
 {
@@ -80,11 +72,6 @@ jerry_port_line_read (jerry_size_t *out_size_p)
   }
 } /* jerry_port_line_read */
 
-/**
- * Free a line buffer allocated by jerry_port_line_read
- *
- * @param buffer_p: buffer that has been allocated by jerry_port_line_read
- */
 void JERRY_ATTR_WEAK
 jerry_port_line_free (jerry_char_t *buffer_p)
 {

jerry-port/unix/jerry-port-unix-date.c

@@ -20,12 +20,6 @@
 #include <sys/time.h>
 #include <time.h>
 
-/**
- * Default implementation of jerry_port_local_tza.
- *
- * @return offset between UTC and local time at the given unix timestamp, if
- *         available. Otherwise, returns 0, assuming UTC time.
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -53,11 +47,6 @@ jerry_port_local_tza (double unix_ms)
 #endif /* HAVE_TM_GMTOFF */
 } /* jerry_port_local_tza */
 
-/**
- * Default implementation of jerry_port_current_time.
- *
- * @return milliseconds since Unix epoch
- */
 double
 jerry_port_current_time (void)
 {

jerry-port/unix/jerry-port-unix-fs.c

@@ -20,44 +20,26 @@
 #include <stdlib.h>
 #include <string.h>
 
-/**
- * Normalize a file path using realpath.
- *
- * @param path_p: input path
- * @param path_size: input path size
- *
- * @return a newly allocated buffer with the normalized path if the operation is successful,
- *         NULL otherwise
- */
 jerry_char_t *
-jerry_port_path_normalize (const jerry_char_t *path_p, /**< input path */
+jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size)
-                           jerry_size_t path_size) /**< size of the path */
 {
   (void) path_size;
 
   return (jerry_char_t *) realpath ((char *) path_p, NULL);
 } /* jerry_port_path_normalize */
 
-/**
- * Free a path buffer returned by jerry_port_path_normalize.
- */
 void
 jerry_port_path_free (jerry_char_t *path_p)
 {
   free (path_p);
 } /* jerry_port_path_free */
 
-/**
- * Computes the end of the directory part of a path.
- *
- * @return end of the directory part of a path.
- */
 jerry_size_t JERRY_ATTR_WEAK
-jerry_port_path_base (const jerry_char_t *path_p) /**< path */
+jerry_port_path_base (const jerry_char_t *path_p)
 {
   const jerry_char_t *basename_p = (jerry_char_t *) strrchr ((char *) path_p, '/') + 1;
 
   return (jerry_size_t) (basename_p - path_p);
-} /* jerry_port_get_directory_end */
+} /* jerry_port_path_base */
 
 #endif /* defined(__unix__) || defined(__APPLE__) */

jerry-port/unix/jerry-port-unix-process.c

@@ -25,11 +25,8 @@
 
 #include <unistd.h>
 
-/**
- * Default implementation of jerry_port_sleep, uses 'usleep'.
- */
 void
-jerry_port_sleep (uint32_t sleep_time) /**< milliseconds to sleep */
+jerry_port_sleep (uint32_t sleep_time)
 {
   usleep ((useconds_t) sleep_time * 1000);
 } /* jerry_port_sleep */

jerry-port/win/jerry-port-win-date.c

@@ -72,12 +72,6 @@ filetime_to_unix_time (LPFILETIME ft_p)
   return (double) (((LONGLONG) date.QuadPart - UNIX_EPOCH_IN_TICKS) / TICKS_PER_MS);
 } /* filetime_to_unix_time */
 
-/**
- * Default implementation of jerry_port_local_tza.
- *
- * @return offset between UTC and local time at the given unix timestamp, if
- *         available. Otherwise, returns 0, assuming UTC time.
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -115,11 +109,6 @@ jerry_port_local_tza (double unix_ms)
   return 0;
 } /* jerry_port_local_tza */
 
-/**
- * Default implementation of jerry_port_current_time.
- *
- * @return milliseconds since Unix epoch
- */
 double
 jerry_port_current_time (void)
 {

jerry-port/win/jerry-port-win-fs.c

@@ -20,37 +20,20 @@
 #include <stdlib.h>
 #include <string.h>
 
-/**
- * Normalize a file path.
- *
- * @return a newly allocated buffer with the normalized path if the operation is successful,
- *         NULL otherwise
- */
 jerry_char_t *
-jerry_port_path_normalize (const jerry_char_t *path_p, /**< input path */
+jerry_port_path_normalize (const jerry_char_t *path_p, jerry_size_t path_size)
-                           jerry_size_t path_size) /**< size of the path */
 {
   (void) path_size;
 
   return (jerry_char_t *) _fullpath (NULL, path_p, _MAX_PATH);
 } /* jerry_port_path_normalize */
 
-/**
- * Free a path buffer returned by jerry_port_path_normalize.
- */
 void
 jerry_port_path_free (jerry_char_t *path_p)
 {
   free (path_p);
 } /* jerry_port_path_free */
 
-/**
- * Get the end of the directory part of the input path.
- *
- * @param path_p: input zero-terminated path string
- *
- * @return offset of the directory end in the input path string
- */
 jerry_size_t
 jerry_port_path_base (const jerry_char_t *path_p)
 {

jerry-port/win/jerry-port-win-process.c

@@ -80,11 +80,8 @@ jerry_port_init (void)
   }
 } /* jerry_port_init */
 
-/**
- * Default implementation of jerry_port_sleep, uses 'Sleep'.
- */
 void
-jerry_port_sleep (uint32_t sleep_time) /**< milliseconds to sleep */
+jerry_port_sleep (uint32_t sleep_time)
 {
   Sleep (sleep_time);
 } /* jerry_port_sleep */

targets/baremetal-sdk/espressif/main/jerry-port.c

@@ -30,35 +30,20 @@
 
 static const char ESP_JS_TAG[] = "JS";
 
-/**
- * Provide log message implementation for the engine.
- */
 void
-jerry_port_log (const char *message_p) /**< message */
+jerry_port_log (const char *message_p)
 {
   ESP_LOGI (ESP_JS_TAG, "%s", message_p);
 } /* jerry_port_log */
 
-/**
- * Implementation of jerry_port_fatal.
- * Calls 'abort' if exit code is non-zero, 'exit' otherwise.
- */
 void
-jerry_port_fatal (jerry_fatal_code_t code) /**< cause of error */
+jerry_port_fatal (jerry_fatal_code_t code)
 {
   ESP_LOGE (ESP_JS_TAG, "Fatal error: %d", code);
   vTaskSuspend (NULL);
   abort ();
 } /* jerry_port_fatal */
 
-/**
- * Default implementation of jerry_port_local_tza. Uses the 'tm_gmtoff' field
- * of 'struct tm' (a GNU extension) filled by 'localtime_r' if available on the
- * system, does nothing otherwise.
- *
- * @return offset between UTC and local time at the given unix timestamp, if
- *         available. Otherwise, returns 0, assuming UTC time.
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -71,13 +56,6 @@ jerry_port_local_tza (double unix_ms)
   return -atoi (buf) * 3600 * 1000 / 100;
 } /* jerry_port_local_tza */
 
-/**
- * Implementation of jerry_port_get_current_time.
- * Uses 'gettimeofday' if available on the system, does nothing otherwise.
- *
- * @return milliseconds since Unix epoch if 'gettimeofday' is available
- *         0 - otherwise.
- */
 double
 jerry_port_current_time (void)
 {

targets/os/mbedos/jerry-port.cpp

@@ -20,20 +20,14 @@
 
 #include "mbed.h"
 
-/**
- * Aborts the program.
- */
 void
 jerry_port_fatal (jerry_fatal_code_t code)
 {
   exit ((int) code);
 } /* jerry_port_fatal */
 
-/**
- * Provide log message implementation for the engine.
- */
 void
-jerry_port_log (const char *message_p) /**< message */
+jerry_port_log (const char *message_p)
 {
   while (*message_p != '\0')
   {
@@ -47,11 +41,6 @@ jerry_port_log (const char *message_p) /**< message */
   }
 } /* jerry_port_log */
 
-/**
- * Dummy function to get the time zone adjustment.
- *
- * @return 0
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -60,11 +49,6 @@ jerry_port_local_tza (double unix_ms)
   return 0;
 } /* jerry_port_local_tza */
 
-/**
- * Implementation of jerry_port_current_time.
- *
- * @return current timer's counter value in milliseconds
- */
 double
 jerry_port_current_time (void)
 {

targets/os/nuttx/jerry-port.c

@@ -19,23 +19,12 @@
 
 #include "jerryscript-port.h"
 
-/**
- * Default implementation of jerry_port_log. Prints log messages to stderr.
- */
 void
-jerry_port_log (const char *message_p) /**< message */
+jerry_port_log (const char *message_p)
 {
   (void) message_p;
 } /* jerry_port_log */
 
-/**
- * Read a line from standard input as a zero-terminated string.
- *
- * @param out_size_p: length of the string
- *
- * @return pointer to the buffer storing the string,
- *         or NULL if end of input
- */
 jerry_char_t *
 jerry_port_line_read (jerry_size_t *out_size_p)
 {
@@ -43,20 +32,12 @@ jerry_port_line_read (jerry_size_t *out_size_p)
   return NULL;
 } /* jerry_port_line_read */
 
-/**
- * Aborts the program.
- */
 void
 jerry_port_fatal (jerry_fatal_code_t code)
 {
   exit ((int) code);
 } /* jerry_port_fatal */
 
-/**
- * Dummy function to get the time zone adjustment.
- *
- * @return 0
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -66,11 +47,6 @@ jerry_port_local_tza (double unix_ms)
   return 0;
 } /* jerry_port_local_tza */
 
-/**
- * Dummy function to get the current time.
- *
- * @return 0
- */
 double
 jerry_port_current_time (void)
 {

targets/os/riot/source/jerry-port.c

@@ -18,11 +18,6 @@
 
 #include "jerryscript-port.h"
 
-/**
- * Dummy function to get the time zone adjustment.
- *
- * @return 0
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -32,11 +27,6 @@ jerry_port_local_tza (double unix_ms)
   return 0;
 } /* jerry_port_local_tza */
 
-/**
- * Dummy function to get the current time.
- *
- * @return 0
- */
 double
 jerry_port_current_time (void)
 {

targets/os/zephyr/src/jerry-port.c

@@ -22,20 +22,12 @@
 
 #include "getline-zephyr.h"
 
-/**
- * Aborts the program.
- */
 void
 jerry_port_fatal (jerry_fatal_code_t code)
 {
   exit ((int) code);
 } /* jerry_port_fatal */
 
-/**
- * Dummy function to get the time zone adjustment.
- *
- * @return 0
- */
 int32_t
 jerry_port_local_tza (double unix_ms)
 {
@@ -45,11 +37,6 @@ jerry_port_local_tza (double unix_ms)
   return 0;
 } /* jerry_port_local_tza */
 
-/**
- * Dummy function to get the current time.
- *
- * @return 0
- */
 double
 jerry_port_current_time (void)
 {
@@ -57,18 +44,12 @@ jerry_port_current_time (void)
   return (double) ms;
 } /* jerry_port_current_time */
 
-/**
- * Provide implementation of jerry_port_sleep.
- */
 void
-jerry_port_sleep (uint32_t sleep_time) /**< milliseconds to sleep */
+jerry_port_sleep (uint32_t sleep_time)
 {
   k_usleep ((useconds_t) sleep_time * 1000);
 } /* jerry_port_sleep */
 
-/**
- * Read line from stdin
- */
 jerry_char_t *
 jerry_port_line_read (jerry_size_t *out_size_p)
 {
@@ -78,9 +59,6 @@ jerry_port_line_read (jerry_size_t *out_size_p)
   return (jerry_char_t *) line_p;
 } /* jerry_port_line_read */
 
-/**
- * Free line, no-op.
- */
 void
 jerry_port_line_free (jerry_char_t *line_p)
 {