Page MenuHomePhabricator

Improve code quality of examples
Closed, ResolvedPublic

Description

We should be exemplifying good code not just code that compiles. I'm thinking:

  • more, descriptive, methods
  • fewer comments that should be self explanatory if better laid out
  • reducing duplications in code as we would in production
  • more whitespace

A simple case that could be much more approachable: https://docs.enlightenment.org/auto/Example_Evas_Box.html

ajwillia.ms lowered the priority of this task from High to Normal.Oct 11 2017, 4:06 PM

There are examples for most or all of the main EFL modules, although their discoverability might be improved. Navigating from https://docs.enlightenment.org/auto/, each link goes to a top level description of a given module, often along with an introductory example or two. Typically, the final sentence of these pages points to a page with additional examples.

For instance, navigating to Eina shows a page with a 2-sentence introduction, a list of links to the autogenerated API reference documentation for Eina's data types and tools, a short Introductory Example, and then "More examples can be found at Eina Examples":

https://docs.enlightenment.org/auto/eina_examples.html

This latter page is a raw list of C files, with no explanation or description apart from the filename. There is also a list of tutorials (several of which are marked TBD or just blank). I'm not sure what the distinction is between examples and tutorials, and wonder if the two lists could be merged?

The raw list appears to be a subset of the files kept in efl/src/examples/eina. E.g. compare the above link with git:

https://git.enlightenment.org/core/efl.git/tree/src/examples/eina

eina_xattr_01.c is in git but not in the docs for example; there may be other discrepancies. I don't know if the docs site is just showing a static snapshot of the examples available in an old EFL release, or if there is a documentation page that requires manual updating. (If the latter, would it be worth changing it to automatically update?)

However, getting back to discoverability, rather than a raw file listing, there might be a better way to organize the examples. See for instance the README I created for Evas' examples:

https://git.enlightenment.org/core/efl.git/tree/src/examples/evas/README

While a README may not be the best solution in general, I think the approach of organizing the examples topically with a brief introduction for each would make it significantly easier for people to find examples relevant to their problems.

Note also that I've specifically called out a few examples as "introductory". In these I've included much more verbose general explanations than in the other more topic-focused examples. I figure advanced users won't want to wade through a lot of re-explaining the basics and will prefer docs to be focused on just the topic at hand, but new users will appreciate the extra hand holding but just one or two examples should be sufficient. Limiting the detailed "tutorial" documentation to just a couple of the examples also helps minimize the amount of documentation effort required.

It may be worthwhile to split this task into per-module subtasks, as the documentation effort will want to prioritize examples for certain modules over others.

I don't know what this module list should be though; I'm assuming the list at https://docs.enlightenment.org/auto/ is out of date?

Eina and parts of Ecore are done - available in examples.git/reference/c/

ajwillia.ms closed this task as Resolved.Jan 4 2018, 4:48 AM

I believe that, for the examples that are being ported (and thus more discoverable) we have done the cleanup required.
There are more comments than I would like but that is mostly to illustrate for tutorial purposes.