[EFL] EFL 문서화 작업 및 관련 글 번역

[ EFL 게시물 목차 : http://seoz.egloos.com/3458699 ]

최근 두달여간 ProFUSION 사가 EFL 문서화 작업을 진행했습니다.
(ProFUSION : http://profusion.mobi/)
그냥 단순한 API reference 뿐만 아니라 예제 코드 및 설명도 추가하고 스크린샷도 추가하는 등 많은 작업을 하였습니다.

며칠전 EFL 의 news 란에 이제 문서화 작업을 마친다는 글이 올라왔습니다. EFL 라이브러리 전반적으로 문서화가 잘 진행이 되었고, 어느정도 목표치에 도달했기 때문에 작업을 마친다는 내용입니다.
(http://trac.enlightenment.org/e/blog/doc-project-end)

하지만 문서화는 끝없이 계속 되어야 하기 때문에 많은 손길이 필요하긴 합니다. 그러므로 앞으로 새로 API 를 추가한다거나 기능을 수정할 때는 API Reference, 예제 코드 및 설명, 스크린샷 등에 신경을 써야 합니다.

지금까지 너무 빈약했던 EFL 의 문서 때문에 고생하셨던 분들은 이번을 계기로 문서를 조금 더 읽어보시길 추천합니다. 저는 특히 예제 코드 및 설명을 해놓은 부분이 마음에 듭니다. 물론 따라하기나 튜토리얼 같은 부분은 없지만, 앞으로 좋은 문서가 더 추가되길 기대해봅니다.

EFL 의 문서는 다음 링크에 있습니다.
http://www.enlightenment.org/p.php?p=docs

ECORE, EVAS, EDJE, ELEMENTARY 등등 각 라이브러리 별로 문서 링크가 있습니다.
예를 들어서 elementary 문서를 보고 싶으시면 Docs 페이지에서 아래 링크를 선택하시면 됩니다.
http://docs.enlightenment.org/auto/elementary/

< 그림 1. Docs 메뉴에서 ELEMENTARY 선택 >

ELEMENTARY 라이브러리 페이지로 들어가면 메인 페이지가 보이고, 우측 상단에 아래와 같이 메뉴가 보입니다.

< 그림 2. ELEMENTARY 문서 >

모든 라이브러리가 이런식으로 문서화된건 아닙니다만 elementary 문서에 있는 메뉴를 살펴보겠습니다.

- Main Page : ELEMENTARY 문서 첫 페이지입니다.
- Infrastructure : 다른 widget 의 기반이 되는 요소들에 대한 설명이 있는 페이지입니다.
- Containers : 다른 widget 을 포함할 수 있는 widget 에 대한 설명이 있는 페이지입니다.
- Widgets : 일반적인 widget 의 설명이 있는 페이지입니다.
- API References : 모든 elementary API 의 설명이 있는 페이지입니다.
- Files : 문서화가 되어있는 파일 목록입니다.

각 widget 별로 예제 코드 및 설명이 있습니다.
그럼 예로, Widgets 메뉴에서 Actionslider 를 선택해보겠습니다. "Detailed Description" 란에 "See an example of actionslider usage here" 라는 글귀가 있습니다. 그럼 here 를 클릭하면 actionslider widget 을 사용하는 예제 코드와 함께 설명이 있습니다.
물론 아주 완벽한 설명은 아니지만, 저는 이 부분이 아주 마음에 듭니다 :)

구조는 다르지만 이와 같이 다른 EFL 라이브러리도 각 구성요소마다 상세한 설명을 볼 수 있습니다.
그럼, news 란에 올라온 Profusion 의 Sachiel 이 쓴 글을 번역해봅니다.

원본 : http://trac.enlightenment.org/e/blog/doc-project-end
번역 : 서주영 2011/08/09

문서화 작업 완료

삼성의 지원을 받아 2달간 진행한 문서화 작업이 끝났습니다. ProFUSION 사의 Jonas Gastal, Rafael Antognolli, Gustavo Lima, Bruno Dilly, Flávio Ceolin 등이 작업에 참여하여 모자란 부분을 채우고 각 컴포넌트에 예제 코드를 추가했습니다.
작업한 내용을 요약하면 아래와 같습니다:

 

ο Eina
    리스트(List) 와 인리스트(Inlist)
    해시(Hash)
    배열(Array)
    Stringshare, strbuf 및 str
    Log, 매직값(Magic) 및 에러(Error)
    반복자(Iterator) 와 접근자(Accessor)
    파일
    타일러(Tiler)
ο Eet 
    기본적인 파일 처리
    사용자 구조체 직렬화(Serialization)
    이미지 읽고 저장하기
ο Evas 
    Canvas 함수, 생성 및 기본 처리
    Evas_Object 를 다루는 일반적인 함수
    각 타입별 함수: Image, Text, Box, Table
    Smart Objects
    Map
    Size hints
ο Ecore 
    메인 루프(The main loop)
    타이머(Timers), animators 및 pollers
    스레드(Threads) pool
    파이프(Pipe)
    File handlers
    이벤트(Events), jobs 및 idlers
    Ecore_Con 과 Ecore_Con_Url
    Ecore_Evas
ο Edje 
    모든 C API (죄송하지만 이번에는 Edc 튜토리얼은 없습니다.)
ο Emotion (드디어 문서화하였습니다!) 
    생성, 재생, 검색 제어
    오디오 제어
    다른 미디어 정보
ο Elementary 
    정말 많은 부분을 작업했습니다.
    각 widget 별로 작은 스크린샷이 있는 widget 목록이 추가되었습니다.

잘 하기는 했지만 결코 완벽하지는 않습니다. 사용자와 개발자가 어떻게 쓰냐에 달려있습니다. 어떤 것을 써야 하는지는 알지만 어떻게 써야하는지 모를 때 문서를 읽으세요. 어떤 것을 써야 하는지 모를 때에는 한번 둘러보세요.

전체적으로 이해하기 어렵다거나 문서화된 것과 프로그램 실행 결과가 다르거나 문서나 코드에 버그가 있거나 하는 등의 문제가 있으면 이야기해주세요. 코드가 그렇듯이 사람들이 얼마나 많이 사용해서 다듬느냐에 달려있습니다. 문서화 프로젝트는 끝났을지 모르지만, 문서화 자체는 계속 됩니다. 

글쓴 날짜: 2011-08-07 03:53
작성자: Sachiel
분류: documentation EFL

아래는 원문입니다.

Got docs?

Two months passed, and with them the documentation project sponsored by Samsung came to an end. During this time, ProFUSION guys Jonas Gastal, Rafael Antognolli, Gustavo Lima, Bruno Dilly, Flávio Ceolin and yours truly, covered several aspects of the EFL adding documentation where it was missing, expanding when it was not enough and writing examples of each component to help make sense out of them.

A summary of what was done:

ο Eina
    List and Inlist
    Hash
    Array
    Stringshare, strbuf and str
    Log, Magic and Error
    Iterator and Accessor
    File
    Tiler
ο Eet
    Basic file operations
    Serialization of user structures
    Image saving and loading
ο Evas
    Canvas functions, creation and basic handling
    General manipulation of Evas_Object's
    Functions specific to each type of object: Image, Text, Box, Table
    Smart Objects
    Map
    Size hints
ο Ecore
    The main loop
    Timers, animators and pollers
    Threads pool
    Pipe
    File handlers
    Events, jobs and idlers
    Ecore_Con and Ecore_Con_Url
    Ecore_Evas
ο Edje
    The entire C API (sorry, no Edc tutorials this time around)
ο Emotion (Yes! It is documented now!)
    Creation, play and seek controls
    Audio controls
    Other media info
ο Elementary
    Errr... a lot really.
    There's a widget list now in the docs with a preview screenshot of each.

A lot of good work has been done, but in no way this means it's perfect. It's up to users and developers now to use these weird new things we were not used to before (the docs, get it?). Read them when you know what you want but are not sure of how to use it. Browse them when you don't know what to use and discover a world of possibilities (I'm getting a bit cheesy here).

And report back any problems. Things are not entirely clear? Something documented doesn't match the program's result? Is that a bug in the documentation or in the code? Just like any other piece of code written, it will improve as people uses it and the rough edges get polished. The project may have ended, but the work itself goes on.

Posted: 2011-08-07 03:53
Author: Sachiel
Categories: documentation EFL

혹시 이 글을 보는 분들 중에서도 문서가 잘못되어 있거나 오탈자를 발견하신 분은 저에게 말씀해주세요. 바로 수정하겠습니다 :)

[ EFL 게시물 목차 : http://seoz.egloos.com/3458699 ]