[jira] [Updated] (WEAVER-1) Enhance [weaver] documentation

["Bruno P. Kinoshita (JIRA)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/WEAVER-1?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Bruno P. Kinoshita updated WEAVER-1:
------------------------------------

    Attachment: WEAVER-1.patch

Hi!

This is my first try at enhancing the [weaver] documentation. This issue 
has been raised during the 1.0 release vote [1]. Feedback is welcome, no 
hard feelings :-)

One of the reasons why I think other devs mentioned the [weaver] docs during the vote
is that it is not so easy to really understand what it does. Actually, I only 
understood after I tried to implement a simple weaver - and I know there are 
other parts of the code that I still have to learn. 

The patch attached includes the following changes:

- Due to the typography, I believe that the topics are misleading. It is 
not easy to distinguish the header levels (e.g. Core Framework and Weaver Modules 
are in the same level as What is this thing, but they complement the first 
chapter being part of a list of what weaver consists of. This patch adds a list 
to the first chapter and puts each list item as a h3 header right below.

- A picture is worth a thousand words :) Did a quick illustration with the 
Maven modules. Used Inkscape for this, source and PNG attached as well. Font 
used: Ungraphic in Ubuntu.

- Examples are a good way to learn too. And although there are (great) examples 
like the privilizer and the normalizer modules, as well as unit tests; I think 
a shorter example could help too. I have included an example based on what I've 
seen in Jenkins API. It scans the code for methods annotated with @WebExposed, 
and simply prints the methods names. But the example given is that a developer 
could automatically generate an REST API (though this part is not covered in 
the example).

Thank you guys for the hard work on this great new component!

> Enhance [weaver] documentation
> ------------------------------
>
>                 Key: WEAVER-1
>                 URL: https://issues.apache.org/jira/browse/WEAVER-1
>             Project: Commons Weaver
>          Issue Type: Improvement
>            Reporter: Bruno P. Kinoshita
>            Assignee: Bruno P. Kinoshita
>            Priority: Minor
>              Labels: docuentation
>         Attachments: WEAVER-1.patch
>
>
> Enhance the documentation of [weaver] component. We can maybe add a user's guide, a 5 minute introduction, images or re-format the existing documentation.



--
This message was sent by Atlassian JIRA
(v6.2#6252)