Page MenuHomePhabricator

Review and improve some legacy doxygen API
Open, WishlistPublic

Description

Some component won't be converted to the Eo object system. This is especially true for Eina, Emile and Eet which are a base layer of our infrastructure. These are currently being documented using doxygen. It would be good to review this (as a background task) and make sure that this documentation is usable. The directory concerned by this are src/lib/eina, src/lib/emile and src/lib/eet.

The copyediting should address spelling, grammar, and formatting standardization. If doxygen is missing for any non-deprecated API, either add it if it's simple enough, or make a note below for follow-up. Some of these files have tutorials/examples embedded as well; skip work on them and just add a note below of ones needing dealt with later.

  • eet/Eet.h
  • eina/eina_accessor.h - has tutorial for the eina_accessor_01.c example
  • eina/eina_alloca.h (D5461)
  • eina/eina_array.h (D6043) - has tutorial for the eina_array_01.c and eina_array_02.c examples (replaced by eina_array.c)
  • eina/eina_benchmark.h (D6502) - has tutorial
  • eina/eina_bezier.h (D5835, D6039)
  • eina/eina_binbuf.h (D6503)
  • eina/eina_binshare.h - has tutorial
  • eina/eina_clist.h
  • eina/eina_config.h
  • eina/eina_convert.h
  • eina/eina_counter.h
  • eina/eina_cow.h
  • eina/eina_cpu.h
  • eina/eina_crc.h (D5468)
  • eina/eina_debug.h
  • eina/eina_error.h - has a tutorial
  • eina/eina_evlog.h
  • eina/eina_file_common.h
  • eina/eina_file.h - has a tutorial for the eina_file_01.c example
  • eina/eina_fp.h
  • eina/eina_freeq.h
  • eina/Eina.h
  • eina/eina_hamster.h
  • eina/eina_hash.h - (D5851, D5834) has a tutorial for the eina_hash_*.c examples (replaced by eina_hash.c)
  • eina/eina_inarray.h - has a tutorial for the eina_inarray_01.c, eina_inarray_02.c, and eina_inarray_03.c examples
  • eina/eina_inlist.h - has a tutorial for the eina_inlist_01.c, eina_inlist_02.c, and eina_inlist_03.c examples
  • eina/eina_iterator.h - has a tutorial for the eina_iterator_01.c example (replaced by eina_iterator.c)
  • eina/eina_lalloc.h
  • eina/eina_list.h - (D5837) has a tutorial for the eina_list_*.c examples (replaced by eina_list.c)
  • eina/eina_lock.h
  • eina/eina_log.h - has a tutorial for the eina_log_01.c, eina_log_02.c, and eina_log_03.c examples
  • eina/eina_magic.h - has a tutorial for the eina_magic_01.c example
  • eina/eina_main.h
  • eina/eina_matrix.h (D5918, D6021)
  • eina/eina_matrixsparse.h (D5425, D5849, D5924)
  • eina/eina_mempool.h
  • eina/eina_mmap.h
  • eina/eina_module.h
  • eina/eina_prefix.h
  • eina/eina_promise.h
  • eina/eina_quad.h
  • eina/eina_quadtree.h (D5522)
  • eina/eina_quaternion.h
  • eina/eina_rbtree.h
  • eina/eina_rectangle.h (D5450, D5785, D5836)
  • eina/eina_refcount.h
  • eina/eina_safepointer.h
  • eina/eina_safety_checks.h
  • eina/eina_sched.h
  • eina/eina_share_common.h
  • eina/eina_simple_xml_parser.h - has a tutorial for the eina_simple_xml_parser_01.c example
  • eina/eina_slice.h
  • eina/eina_slstr.h
  • eina/eina_strbuf_common.h
  • eina/eina_strbuf.h - has a tutorial for the eina_strbuf_01.c example (replaced by eina_string.c)
  • eina/eina_str.h - has a tutorial for the eina_str_01.c example (replaced by eina_string.c)
  • eina/eina_stringshare.h - has a tutorial for the eina_stringshare_01.c example (replaced by eina_string.c)
  • eina/eina_thread.h
  • eina/eina_thread_queue.h
  • eina/eina_tiler.h - has tutorial for the eina_tiler_01.c example
  • eina/eina_tmpstr.h
  • eina/eina_trash.h
  • eina/eina_types.h
  • eina/eina_unicode.h
  • eina/eina_ustrbuf.h
  • eina/eina_ustringshare.h
  • eina/eina_util.h
  • eina/eina_value.h - has a tutorial for the eina_value_01.c, eina_value_02.c, eina_value_03.c, eina_value_04.c examples (replaced by eina_value.c and eina_value_custom.c))
  • eina/eina_value_util.h
  • eina/eina_vector.h
  • eina/eina_xattr.h
  • eina/eina_binbuf_template_c.x
  • eina/eina_inline_array.x
  • eina/eina_inline_lock_barrier.x
  • eina/eina_inline_lock_posix.x
  • eina/eina_inline_log.x
  • eina/eina_inline_mempool.x
  • eina/eina_inline_modinfo.x
  • eina/eina_inline_rbtree.x (D5460)
  • eina/eina_inline_stringshare.x
  • eina/eina_inline_str.x
  • eina/eina_inline_tiler.x
  • eina/eina_inline_ustringshare.x
  • eina/eina_inline_value_util.x
  • eina/eina_inline_value.x
  • emile/emile_base64.h
  • emile/emile_cipher.h
  • emile/emile_compress.h
  • emile/Emile.h
  • emile/emile_image.h
zmike added a project: efl.Aug 22 2017, 3:42 PM
cedric added a comment.Oct 2 2017, 3:29 PM

This is also a filler task, done on the back burner like T5832 .

I actually forgot, but there is some significant amount of doxygen also in src/lib/eo .

bryceharrington updated the task description. (Show Details)
bryceharrington updated the task description. (Show Details)

The diff attached to https://phab.enlightenment.org/D5468 shows the doxygen style to follow. Specifically, I've derived the following rules-of-thumb from examining the existing style of the Eina and Evas doxygen in the codebase, to try and standardize on. Please let me know if any adjustments need made to these.

Briefs:

  • Always specify @brief
  • Strive to keep the @brief text to 1 line

Parameters:

  • Always indicate [in], [out], and [in,out]. E.g. param[in]
  • Use a capitalized word (usually "The") to start the param's definition text.
  • Avoid multi-line @param definitions, but where unavoidable indent the second line to the start of the parameter name from the first line. Move any elaboration beyond this down to the main body text for the routine.
  • When referencing the parameter name in the text, @return, or in other @param definitions, use "@p name" rather than the lengthier "the given name parameter" or similar.
  • Try to avoid line breaking wraps between "@p" and the parameter name; keep "@p name" on the same line.

Constants:

  • EFL-specific defines should be hash-prefixed, like #EINA_TRUE.
  • Other constants should be marked with @c. E.g. @c 0xffffffff
  • NULL should be specified as @c NULL, but not when part of a compound word such as NULL-terminated or non-NULL.
  • NUL is the character literal '\0', not to be confused with NULL. Strings are NUL-terminated. The empty string "" is thus equal to NUL, but the pointer to it is non-NULL. :-D

Example code inlined should be:

  • Introduced with "Example:" or "Example usage for ____:" with a linespace before and after.
  • Kept extremely short, otherwise break it out from doxygen into a proper example code.
  • Marked off with @code / @endcode

External URL reference links should be:

  • Bracketed from the text using parens (http://foo.bar)
  • Point to places unlikely to bitrot. Use web.archive.org for links highly likely to bitrot.
  • Avoided in @see references, which should focus on internal cross-references.
  • Left without a terminating period (autolinking can misinterpret the period as part of the URL and thus break the link)

Body text

  • Wrap lines to 72-80 columns, but don't be overstrict - if a long variable or function name needs a longer line, or if going a few characters beyond 80 allows everything to be on one line, it's ok.
  • If multiple paragraphs are used, the first should be introductory and answer the questions, "What does this routine do? Why would I want to use it?"
  • If there are multiple ways to use the routine, try organizing each use case as a separate paragraph even if it makes a bit of redundancy; the person interested in that use case will have all the info at hand without confusion from alternate uses.

Section spacing

  • Always a linespace after @brief
  • @param's and @return should all be in one block with no linespacing between them.
  • @see should be after the doxygen body text, and separated from it with line-space. Multiple @see's should not have linespace between them, but there should be linespaces between the block of @see's and any other doxygen elements before or after.

The @since line should be at the very end of the doxygen block, with a blank doxygen linespace before it.

bryceharrington removed a subscriber: c.Nov 13 2017, 5:49 PM
ajwillia.ms updated the task description. (Show Details)Nov 22 2017, 4:01 AM
zmike edited projects, added Restricted Project; removed efl.Jun 11 2018, 6:57 AM
bu5hm4n edited projects, added efl: docs; removed Restricted Project.Jun 11 2018, 8:23 AM
mattzamudio updated the task description. (Show Details)Aug 17 2018, 2:45 PM
mattzamudio updated the task description. (Show Details)
mattzamudio updated the task description. (Show Details)
mattzamudio updated the task description. (Show Details)Aug 17 2018, 3:21 PM
mattzamudio updated the task description. (Show Details)
mattzamudio updated the task description. (Show Details)Aug 17 2018, 6:53 PM