improve which doc line is the first because this one is displayed in docs in the overview

This commit is contained in:
Vinzenz Schroeter 2024-09-07 14:44:25 +02:00
parent acc35b6727
commit c712b037d0
6 changed files with 140 additions and 101 deletions

View file

@ -25,7 +25,7 @@ int main(void) {
sp_pixel_grid_fill(pixels, true);
SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
while (sp_connection_send(connection, sp_command_clone(command)));
while (sp_connection_send_command(connection, sp_command_clone(command)));
sp_packet_free(packet);
sp_connection_free(connection);

View file

@ -112,8 +112,8 @@ typedef struct SPBrightnessGrid SPBrightnessGrid;
* # Examples
*
* ```C
* sp_connection_send(connection, sp_command_clear());
* sp_connection_send(connection, sp_command_brightness(5));
* sp_connection_send_command(connection, sp_command_clear());
* sp_connection_send_command(connection, sp_command_brightness(5));
* ```
*/
typedef struct SPCommand SPCommand;
@ -126,7 +126,7 @@ typedef struct SPCommand SPCommand;
* ```C
* CConnection connection = sp_connection_open("172.23.42.29:2342");
* if (connection != NULL)
* sp_connection_send(connection, sp_command_clear());
* sp_connection_send_command(connection, sp_command_clear());
* ```
*/
typedef struct SPConnection SPConnection;
@ -537,9 +537,6 @@ struct SPByteSlice sp_brightness_grid_unsafe_data_ref(struct SPBrightnessGrid *t
size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_);
/**
* Allocates a new `Command::BitmapLinear` instance.
* The passed `SPBitVec` gets consumed.
*
* Set pixel data starting at the pixel offset on screen.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -547,6 +544,10 @@ size_t sp_brightness_grid_width(const struct SPBrightnessGrid *this_);
*
* The contained `SPBitVec` is always uncompressed.
*
* The passed `SPBitVec` gets consumed.
*
* Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
@ -562,9 +563,6 @@ struct SPCommand *sp_command_bitmap_linear(size_t offset,
SPCompressionCode compression);
/**
* Allocates a new `Command::BitmapLinearAnd` instance.
* The passed `SPBitVec` gets consumed.
*
* Set pixel data according to an and-mask starting at the offset.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -572,6 +570,10 @@ struct SPCommand *sp_command_bitmap_linear(size_t offset,
*
* The contained `SPBitVec` is always uncompressed.
*
* The passed `SPBitVec` gets consumed.
*
* Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
@ -587,9 +589,6 @@ struct SPCommand *sp_command_bitmap_linear_and(size_t offset,
SPCompressionCode compression);
/**
* Allocates a new `Command::BitmapLinearOr` instance.
* The passed `SPBitVec` gets consumed.
*
* Set pixel data according to an or-mask starting at the offset.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -597,6 +596,10 @@ struct SPCommand *sp_command_bitmap_linear_and(size_t offset,
*
* The contained `SPBitVec` is always uncompressed.
*
* The passed `SPBitVec` gets consumed.
*
* Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
@ -612,12 +615,11 @@ struct SPCommand *sp_command_bitmap_linear_or(size_t offset,
SPCompressionCode compression);
/**
* Allocates a new `Command::BitmapLinearWin` instance.
* The passed `SPPixelGrid` gets consumed.
*
* Sets a window of pixels to the specified values.
*
* Will never return NULL.
* The passed `SPPixelGrid` gets consumed.
*
* Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
*
* # Safety
*
@ -635,9 +637,6 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x,
SPCompressionCode compression_code);
/**
* Allocates a new `Command::BitmapLinearXor` instance.
* The passed `SPBitVec` gets consumed.
*
* Set pixel data according to a xor-mask starting at the offset.
*
* The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -645,6 +644,10 @@ struct SPCommand *sp_command_bitmap_linear_win(size_t x,
*
* The contained `SPBitVec` is always uncompressed.
*
* The passed `SPBitVec` gets consumed.
*
* Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
@ -660,8 +663,9 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset,
SPCompressionCode compression);
/**
* Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the
* same value.
* Set the brightness of all tiles to the same value.
*
* Returns: a new `Command::Brightness` instance. Will never return NULL.
*
* # Panics
*
@ -677,10 +681,11 @@ struct SPCommand *sp_command_bitmap_linear_xor(size_t offset,
struct SPCommand *sp_command_brightness(uint8_t brightness);
/**
* Allocates a new `Command::CharBrightness` instance.
* Set the brightness of individual tiles in a rectangular area of the display.
*
* The passed `SPBrightnessGrid` gets consumed.
*
* Set the brightness of individual tiles in a rectangular area of the display.
* Returns: a new `Command::CharBrightness` instance. Will never return NULL.
*
* # Safety
*
@ -696,14 +701,16 @@ struct SPCommand *sp_command_char_brightness(size_t x,
struct SPBrightnessGrid *grid);
/**
* Allocates a new `Command::Clear` instance.
* Set all pixels to the off state.
*
* Set all pixels to the off state. Does not affect brightness.
* Does not affect brightness.
*
* Returns: a new `Command::Clear` instance. Will never return NULL.
*
* # Examples
*
* ```C
* sp_connection_send(connection, sp_command_clear());
* sp_connection_send_command(connection, sp_command_clear());
* ```
*
* # Safety
@ -730,9 +737,6 @@ struct SPCommand *sp_command_clear(void);
struct SPCommand *sp_command_clone(const struct SPCommand *original);
/**
* Allocates a new `Command::Cp437Data` instance.
* The passed `SPCp437Grid` gets consumed.
*
* Show text on the screen.
*
* <div class="warning">
@ -740,7 +744,9 @@ struct SPCommand *sp_command_clone(const struct SPCommand *original);
* Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
* </div>
*
* Will never return NULL.
* The passed `SPCp437Grid` gets consumed.///
*
* Returns: a new `Command::Cp437Data` instance. Will never return NULL.
*
* # Safety
*
@ -756,7 +762,9 @@ struct SPCommand *sp_command_cp437_data(size_t x,
struct SPCp437Grid *grid);
/**
* Allocates a new `Command::FadeOut` instance.
* A yet-to-be-tested command.
*
* Returns: a new `Command::FadeOut` instance. Will never return NULL.
*
* # Safety
*
@ -788,11 +796,12 @@ struct SPCommand *sp_command_fade_out(void);
void sp_command_free(struct SPCommand *ptr);
/**
* Allocates a new `Command::HardReset` instance.
*
* Kills the udp daemon on the display, which usually results in a restart.
*
* Please do not send this in your normal program flow.
*
* Returns: a new `Command::HardReset` instance. Will never return NULL.
*
* # Safety
*
* The caller has to make sure that:
@ -803,7 +812,9 @@ void sp_command_free(struct SPCommand *ptr);
struct SPCommand *sp_command_hard_reset(void);
/**
* Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process.
* Tries to turn a `SPPacket` into a `SPCommand`.
*
* The packet is deallocated in the process.
*
* Returns: pointer to new `SPCommand` instance or NULL
*
@ -851,6 +862,7 @@ struct SPConnection *sp_connection_open(const char *host);
/**
* Sends a `SPCommand` to the display using the `SPConnection`.
*
* The passed `SPCommand` gets consumed.
*
* returns: true in case of success
@ -868,6 +880,7 @@ bool sp_connection_send_command(const struct SPConnection *connection,
/**
* Sends a `SPPacket` to the display using the `SPConnection`.
*
* The passed `SPPacket` gets consumed.
*
* returns: true in case of success

View file

@ -20,8 +20,8 @@ use crate::{
/// # Examples
///
/// ```C
/// sp_connection_send(connection, sp_command_clear());
/// sp_connection_send(connection, sp_command_brightness(5));
/// sp_connection_send_command(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_brightness(5));
/// ```
pub struct SPCommand(pub(crate) servicepoint::Command);
@ -31,7 +31,9 @@ impl Clone for SPCommand {
}
}
/// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process.
/// Tries to turn a `SPPacket` into a `SPCommand`.
///
/// The packet is deallocated in the process.
///
/// Returns: pointer to new `SPCommand` instance or NULL
///
@ -72,14 +74,16 @@ pub unsafe extern "C" fn sp_command_clone(
Box::into_raw(Box::new((*original).clone()))
}
/// Allocates a new `Command::Clear` instance.
/// Set all pixels to the off state.
///
/// Set all pixels to the off state. Does not affect brightness.
/// Does not affect brightness.
///
/// Returns: a new `Command::Clear` instance. Will never return NULL.
///
/// # Examples
///
/// ```C
/// sp_connection_send(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_clear());
/// ```
///
/// # Safety
@ -93,11 +97,12 @@ pub unsafe extern "C" fn sp_command_clear() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::Clear)))
}
/// Allocates a new `Command::HardReset` instance.
///
/// Kills the udp daemon on the display, which usually results in a restart.
///
/// Please do not send this in your normal program flow.
///
/// Returns: a new `Command::HardReset` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -109,7 +114,9 @@ pub unsafe extern "C" fn sp_command_hard_reset() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::HardReset)))
}
/// Allocates a new `Command::FadeOut` instance.
/// A yet-to-be-tested command.
///
/// Returns: a new `Command::FadeOut` instance. Will never return NULL.
///
/// # Safety
///
@ -122,8 +129,9 @@ pub unsafe extern "C" fn sp_command_fade_out() -> *mut SPCommand {
Box::into_raw(Box::new(SPCommand(servicepoint::Command::FadeOut)))
}
/// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the
/// same value.
/// Set the brightness of all tiles to the same value.
///
/// Returns: a new `Command::Brightness` instance. Will never return NULL.
///
/// # Panics
///
@ -146,10 +154,11 @@ pub unsafe extern "C" fn sp_command_brightness(
))))
}
/// Allocates a new `Command::CharBrightness` instance.
/// Set the brightness of individual tiles in a rectangular area of the display.
///
/// The passed `SPBrightnessGrid` gets consumed.
///
/// Set the brightness of individual tiles in a rectangular area of the display.
/// Returns: a new `Command::CharBrightness` instance. Will never return NULL.
///
/// # Safety
///
@ -172,9 +181,6 @@ pub unsafe extern "C" fn sp_command_char_brightness(
))))
}
/// Allocates a new `Command::BitmapLinear` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data starting at the pixel offset on screen.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -182,6 +188,10 @@ pub unsafe extern "C" fn sp_command_char_brightness(
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -205,9 +215,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
))))
}
/// Allocates a new `Command::BitmapLinearAnd` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to an and-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -215,6 +222,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear(
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -238,9 +249,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
))))
}
/// Allocates a new `Command::BitmapLinearOr` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to an or-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -248,6 +256,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_and(
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -271,9 +283,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
))))
}
/// Allocates a new `Command::BitmapLinearXor` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to a xor-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -281,6 +290,10 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_or(
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -304,9 +317,6 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
))))
}
/// Allocates a new `Command::Cp437Data` instance.
/// The passed `SPCp437Grid` gets consumed.
///
/// Show text on the screen.
///
/// <div class="warning">
@ -314,7 +324,9 @@ pub unsafe extern "C" fn sp_command_bitmap_linear_xor(
/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
/// </div>
///
/// Will never return NULL.
/// The passed `SPCp437Grid` gets consumed.///
///
/// Returns: a new `Command::Cp437Data` instance. Will never return NULL.
///
/// # Safety
///
@ -337,12 +349,11 @@ pub unsafe extern "C" fn sp_command_cp437_data(
))))
}
/// Allocates a new `Command::BitmapLinearWin` instance.
/// The passed `SPPixelGrid` gets consumed.
///
/// Sets a window of pixels to the specified values.
///
/// Will never return NULL.
/// The passed `SPPixelGrid` gets consumed.
///
/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
///
/// # Safety
///

View file

@ -14,7 +14,7 @@ use crate::{SPCommand, SPPacket};
/// ```C
/// CConnection connection = sp_connection_open("172.23.42.29:2342");
/// if (connection != NULL)
/// sp_connection_send(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_clear());
/// ```
pub struct SPConnection(pub(crate) servicepoint::Connection);
@ -46,6 +46,7 @@ pub unsafe extern "C" fn sp_connection_open(
}
/// Sends a `SPPacket` to the display using the `SPConnection`.
///
/// The passed `SPPacket` gets consumed.
///
/// returns: true in case of success
@ -67,6 +68,7 @@ pub unsafe extern "C" fn sp_connection_send_packet(
}
/// Sends a `SPCommand` to the display using the `SPConnection`.
///
/// The passed `SPCommand` gets consumed.
///
/// returns: true in case of success

View file

@ -17,7 +17,7 @@
//! sp_pixel_grid_fill(pixels, true);
//!
//! SPCommand *command = sp_command_bitmap_linear_win(0, 0, pixels, Uncompressed);
//! while (sp_connection_send(connection, sp_command_clone(command)));
//! while (sp_connection_send_command(connection, sp_command_clone(command)));
//!
//! sp_packet_free(packet);
//! sp_connection_free(connection);

View file

@ -372,7 +372,9 @@ namespace ServicePoint.BindGen
public static extern ByteSlice sp_brightness_grid_unsafe_data_ref(BrightnessGrid* @this);
/// <summary>
/// Tries to turn a `SPPacket` into a `SPCommand`. The packet is deallocated in the process.
/// Tries to turn a `SPPacket` into a `SPCommand`.
///
/// The packet is deallocated in the process.
///
/// Returns: pointer to new `SPCommand` instance or NULL
///
@ -405,14 +407,16 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_clone(Command* original);
/// <summary>
/// Allocates a new `Command::Clear` instance.
/// Set all pixels to the off state.
///
/// Set all pixels to the off state. Does not affect brightness.
/// Does not affect brightness.
///
/// Returns: a new `Command::Clear` instance. Will never return NULL.
///
/// # Examples
///
/// ```C
/// sp_connection_send(connection, sp_command_clear());
/// sp_connection_send_command(connection, sp_command_clear());
/// ```
///
/// # Safety
@ -426,11 +430,12 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_clear();
/// <summary>
/// Allocates a new `Command::HardReset` instance.
///
/// Kills the udp daemon on the display, which usually results in a restart.
///
/// Please do not send this in your normal program flow.
///
/// Returns: a new `Command::HardReset` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -442,7 +447,9 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_hard_reset();
/// <summary>
/// Allocates a new `Command::FadeOut` instance.
/// A yet-to-be-tested command.
///
/// Returns: a new `Command::FadeOut` instance. Will never return NULL.
///
/// # Safety
///
@ -455,8 +462,9 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_fade_out();
/// <summary>
/// Allocates a new `Command::Brightness` instance for setting the brightness of all tiles to the
/// same value.
/// Set the brightness of all tiles to the same value.
///
/// Returns: a new `Command::Brightness` instance. Will never return NULL.
///
/// # Panics
///
@ -473,10 +481,11 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_brightness(byte brightness);
/// <summary>
/// Allocates a new `Command::CharBrightness` instance.
/// Set the brightness of individual tiles in a rectangular area of the display.
///
/// The passed `SPBrightnessGrid` gets consumed.
///
/// Set the brightness of individual tiles in a rectangular area of the display.
/// Returns: a new `Command::CharBrightness` instance. Will never return NULL.
///
/// # Safety
///
@ -491,9 +500,6 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_char_brightness(nuint x, nuint y, BrightnessGrid* grid);
/// <summary>
/// Allocates a new `Command::BitmapLinear` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data starting at the pixel offset on screen.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -501,6 +507,10 @@ namespace ServicePoint.BindGen
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinear` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -515,9 +525,6 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_bitmap_linear(nuint offset, BitVec* bit_vec, CompressionCode compression);
/// <summary>
/// Allocates a new `Command::BitmapLinearAnd` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to an and-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -525,6 +532,10 @@ namespace ServicePoint.BindGen
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearAnd` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -539,9 +550,6 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_bitmap_linear_and(nuint offset, BitVec* bit_vec, CompressionCode compression);
/// <summary>
/// Allocates a new `Command::BitmapLinearOr` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to an or-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -549,6 +557,10 @@ namespace ServicePoint.BindGen
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearOr` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -563,9 +575,6 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_bitmap_linear_or(nuint offset, BitVec* bit_vec, CompressionCode compression);
/// <summary>
/// Allocates a new `Command::BitmapLinearXor` instance.
/// The passed `SPBitVec` gets consumed.
///
/// Set pixel data according to a xor-mask starting at the offset.
///
/// The screen will continuously overwrite more pixel data without regarding the offset, meaning
@ -573,6 +582,10 @@ namespace ServicePoint.BindGen
///
/// The contained `SPBitVec` is always uncompressed.
///
/// The passed `SPBitVec` gets consumed.
///
/// Returns: a new `Command::BitmapLinearXor` instance. Will never return NULL.
///
/// # Safety
///
/// The caller has to make sure that:
@ -587,9 +600,6 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_bitmap_linear_xor(nuint offset, BitVec* bit_vec, CompressionCode compression);
/// <summary>
/// Allocates a new `Command::Cp437Data` instance.
/// The passed `SPCp437Grid` gets consumed.
///
/// Show text on the screen.
///
/// &lt;div class="warning"&gt;
@ -597,7 +607,9 @@ namespace ServicePoint.BindGen
/// Because Rust expects UTF-8 strings, it might be necessary to only send ASCII for now.
/// &lt;/div&gt;
///
/// Will never return NULL.
/// The passed `SPCp437Grid` gets consumed.///
///
/// Returns: a new `Command::Cp437Data` instance. Will never return NULL.
///
/// # Safety
///
@ -612,12 +624,11 @@ namespace ServicePoint.BindGen
public static extern Command* sp_command_cp437_data(nuint x, nuint y, Cp437Grid* grid);
/// <summary>
/// Allocates a new `Command::BitmapLinearWin` instance.
/// The passed `SPPixelGrid` gets consumed.
///
/// Sets a window of pixels to the specified values.
///
/// Will never return NULL.
/// The passed `SPPixelGrid` gets consumed.
///
/// Returns: a new `Command::BitmapLinearWin` instance. Will never return NULL.
///
/// # Safety
///
@ -674,6 +685,7 @@ namespace ServicePoint.BindGen
/// <summary>
/// Sends a `SPPacket` to the display using the `SPConnection`.
///
/// The passed `SPPacket` gets consumed.
///
/// returns: true in case of success
@ -692,6 +704,7 @@ namespace ServicePoint.BindGen
/// <summary>
/// Sends a `SPCommand` to the display using the `SPConnection`.
///
/// The passed `SPCommand` gets consumed.
///
/// returns: true in case of success