[POLL] javadocs approach [WAS Re: [MODULARISATION] Stage Two: division into modules]

[robert burrell donkin <ro...@gmail.com>]

On 3/23/07, Stefano Bagnara <ap...@bago.org> wrote:
> robert burrell donkin ha scritto:

<snip>

> >> 2) How should we manage javadocs creation and sdk creation in this
> >> multimodule structure? I think the "move" broke them.
> >
> > it's easy to put them back again but i'd prefer to hear opinions
> > before i implement
> >
> > one approach is for all modules to create src and javadoc jars of
> > their own (useful for IDEs) and then unpack them in deploy. another is
> > to javadoc from the deployment across all modules.
>
> I prefer to have each jar with its own javadocs, and maybe we can unpack
> them all in a single package in the final distribution, but I don't know
> if this is easy to do.

i favour this as well but i'd like to see if there's a consensus
before i implement

- robert

--8<------------------------------------------------------------------------------------------

[ ] Ship -javadoc.jar and -src.jar for each module
[ ] Create javadocs just in the deployment module

-----------------------------------------------------------------------------------------------

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org

Re: [POLL] javadocs approach [WAS Re: [MODULARISATION] Stage Two: division into modules]

[Danny Angus <da...@apache.org>]

On 3/25/07, robert burrell donkin <ro...@gmail.com> wrote:

> > I prefer to have each jar with its own javadocs, and maybe we can unpack
> > them all in a single package in the final distribution, but I don't know
> > if this is easy to do.
>
> i favour this as well but i'd like to see if there's a consensus
> before i implement

+1 from me.
If the modules are divided at the right points of inflexion then the
scope of the docs will naturally encompass a discrete concern. If you
see what I mean. Only changes at an architectural level, and students
of James, would require all the docs in one place.

d.

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org

Re: [POLL] javadocs approach [WAS Re: [MODULARISATION] Stage Two: division into modules]

[Serge Knystautas <sk...@gmail.com>]

On 3/25/07, robert burrell donkin <ro...@gmail.com> wrote:
> On 3/23/07, Stefano Bagnara <ap...@bago.org> wrote:
> > robert burrell donkin ha scritto:
>
> <snip>
>
> > >> 2) How should we manage javadocs creation and sdk creation in this
> > >> multimodule structure? I think the "move" broke them.
> > >
> > > it's easy to put them back again but i'd prefer to hear opinions
> > > before i implement
> > >
> > > one approach is for all modules to create src and javadoc jars of
> > > their own (useful for IDEs) and then unpack them in deploy. another is
> > > to javadoc from the deployment across all modules.
> >
> > I prefer to have each jar with its own javadocs, and maybe we can unpack
> > them all in a single package in the final distribution, but I don't know
> > if this is easy to do.
>
> i favour this as well but i'd like to see if there's a consensus
> before i implement

I like the way spring does it.  You have various dependencies split
into separate jars, but then there's a single big javadoc
(http://static.springframework.org/spring/docs/2.0.x/api/).  It's just
nice to have a comprehensive reference.

I'm not sure how fair a comparison this is as I still need to digest a
bit more how things are divided.

-- 
Serge Knystautas
Lokitech >> software . strategy . design >> http://www.lokitech.com
p. 301.656.5501
e. sergek@lokitech.com

---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org