summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBryce Harrington <bryce@osg.samsung.com>2018-07-03 14:44:41 -0400
committerChris Michael <cp.michael@samsung.com>2018-07-03 14:44:41 -0400
commitf3512bec57925a4ee9091eb375fac043bf3ecf9e (patch)
tree64c1c955f224f907262bb1c5d2d5082126b99a90
parentb4c2db8d05108c2902dc7b3c560f9e52d5d429c4 (diff)
eina: Improve eina_benchmark function documentation
Summary: Define return values as part of @return. Clarify that the returned list of files are gnuplot filenames specifically. Cleanup grammar throughout. Reviewers: zmike, devilhorns Reviewed By: devilhorns Subscribers: cedric, #committers Tags: #efl Differential Revision: https://phab.enlightenment.org/D6502
-rw-r--r--src/lib/eina/eina_benchmark.h32
1 files changed, 13 insertions, 19 deletions
diff --git a/src/lib/eina/eina_benchmark.h b/src/lib/eina/eina_benchmark.h
index 695ad5673a..2024cc498e 100644
--- a/src/lib/eina/eina_benchmark.h
+++ b/src/lib/eina/eina_benchmark.h
@@ -359,14 +359,12 @@ typedef void (*Eina_Benchmark_Specimens)(int request);
359 * 359 *
360 * @param name The name of the benchmark. 360 * @param name The name of the benchmark.
361 * @param run The name of the run. 361 * @param run The name of the run.
362 * @return @c NULL on failure, non @c NULL otherwise. 362 * @return A valid benchmark on success, or @c NULL on memory allocation
363 * failure.
363 * 364 *
364 * This function creates a new benchmark. @p name and @p run are used 365 * This function creates a new benchmark. @p name and @p run are used
365 * to name the gnuplot file that eina_benchmark_run() will create. 366 * to name the gnuplot file that eina_benchmark_run() will create.
366 * 367 *
367 * This function returns a valid benchmark on success, or @c NULL if
368 * memory allocation fails.
369 *
370 * When the new module is not needed anymore, use 368 * When the new module is not needed anymore, use
371 * eina_benchmark_free() to free the allocated memory. 369 * eina_benchmark_free() to free the allocated memory.
372 */ 370 */
@@ -397,13 +395,12 @@ EAPI void eina_benchmark_free(Eina_Benchmark *bench);
397 * 395 *
398 * This function adds the test named @p name to @p benchmark. @p 396 * This function adds the test named @p name to @p benchmark. @p
399 * bench_cb is the function called when the test is executed. That 397 * bench_cb is the function called when the test is executed. That
400 * test can be executed a certain amount of time. @p count_start, @p count_end and 398 * test can be executed a certain number of times, from @p count_start
401 * @p count_step define a loop with a step increment. The integer that is 399 * to @p count_end, with a step increment of @p count_step. This counter
402 * increasing by @p count_step from @p count_start to @p count_end is passed to @p 400 * is passed to @p bench_cb when eina_benchmark_run() is called.
403 * bench_cb when eina_benchmark_run() is called.
404 * 401 *
405 * If @p bench is @c NULL, this function returns immediately. 402 * If @p bench is @c NULL or @p count_step is 0, this function returns
406 * This function returns #EINA_FALSE on failure, #EINA_TRUE otherwise. 403 * immediately and does not add any tests to the benchmark.
407 */ 404 */
408EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench, 405EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
409 const char *name, 406 const char *name,
@@ -413,29 +410,26 @@ EAPI Eina_Bool eina_benchmark_register(Eina_Benchmark *bench,
413 int count_step); 410 int count_step);
414 411
415/** 412/**
416 * @brief Runs the benchmark tests that have been registered. 413 * @brief Runs the benchmark's registered tests.
417 * 414 *
418 * @param bench The benchmark. 415 * @param bench The benchmark.
419 * @return The list of names of the test files. 416 * @return A list of gnuplot filenames for the test results, or @c NULL
417 * on failure.
420 * 418 *
421 * This function runs all the tests that have been registered with 419 * This function runs all the tests that have been registered with
422 * eina_benchmark_register() and saves the result in a gnuplot 420 * eina_benchmark_register() and saves the result in gnuplot
423 * file. The name of the file has the following format: 421 * input files. The filenames have the following format:
424 * 422 *
425 * @code 423 * @code
426 * bench_[name]_[run]%s.gnuplot 424 * bench_[name]_[run]%s.gnuplot
427 * @endcode 425 * @endcode
428 * 426 *
429 * Where [name] and [run] are the values passed to 427 * Where [name] and [run] are the values passed to
430 * eina_benchmark_new(). 428 * eina_benchmark_new() when registering the test.
431 * 429 *
432 * Each registered test is executed and timed. The time is written to 430 * Each registered test is executed and timed. The time is written to
433 * the gnuplot file. The number of times each test is executed is 431 * the gnuplot file. The number of times each test is executed is
434 * controlled by the parameters passed to eina_benchmark_register(). 432 * controlled by the parameters passed to eina_benchmark_register().
435 *
436 * If @p bench is @c NULL, this functions returns @c NULL
437 * immediately. Otherwise, it returns the list of the names of each
438 * test.
439 */ 433 */
440EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench); 434EAPI Eina_Array *eina_benchmark_run(Eina_Benchmark *bench);
441 435