You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cayenne.apache.org by Michael Gentry <mg...@masslight.net> on 2014/10/01 16:41:51 UTC

DI Configuration Docs

I think the DI documentation should include a table/list of all the
configurable elements that are available.

For example, when I was trying to fix my unit tests to override a
value in the model, I had to go digging through the source code to
come up with:

binder.bind(SchemaUpdateStrategy.class).to(CreateIfNoSchemaStrategy.class);

If the documentation had a table/list of available options, it would
be easier for people to find and configure.  For example:

Interface: SchemaUpdateStrategy
Default Implementation: Cayenne Model Value
Supplied Impementations: CreateIfNoSchemaStrategy,
SkipSchemaUpdateStrategy, ThrowOnPartialOrCreateSchemaStrategy,
ThrowOnPartialSchemaStrategy
...


Thoughts?

Thanks,

mrg

Re: DI Configuration Docs

Posted by Andrus Adamchik <an...@objectstyle.org>.
BTW, I recall looking at the Tapestry DI docs from the times of Hivemind and scratching my head trying to understand cryptic docs conventions. With Tapestry 5, opening a .java file that binds those same service is much more enlightening, especially if I am writing my own extension for a given interface.

Andrus

On Oct 1, 2014, at 6:07 PM, Andrus Adamchik <an...@objectstyle.org> wrote:

> I have no objection to better documenting individual important services, but maintaining a text version of ServerModule is probably a losing battle. I'd say we should better highlight this link:
> 
> https://github.com/apache/cayenne/blob/master/cayenne-server/src/main/java/org/apache/cayenne/configuration/server/ServerModule.java#L117
> 
> We are doing it already, but probably not explicitly enough:
> 
> Cayenne Guide, page 61: "While we describe some of them in the following sections, the best way to get a full list is to check the source code of the Cayenne version you are using and namely look in org.apache.cayenne.configuration.server.ServerModule - the main built-in module in Cayenne."
> 
> IMO this approach is one way to strike a balance between providing useful information and overburdening documentation with fine details of many exotic services. 
> 
> Andrus
> 
> On Oct 1, 2014, at 5:41 PM, Michael Gentry <mg...@masslight.net> wrote:
>> I think the DI documentation should include a table/list of all the
>> configurable elements that are available.
>> 
>> For example, when I was trying to fix my unit tests to override a
>> value in the model, I had to go digging through the source code to
>> come up with:
>> 
>> binder.bind(SchemaUpdateStrategy.class).to(CreateIfNoSchemaStrategy.class);
>> 
>> If the documentation had a table/list of available options, it would
>> be easier for people to find and configure.  For example:
>> 
>> Interface: SchemaUpdateStrategy
>> Default Implementation: Cayenne Model Value
>> Supplied Impementations: CreateIfNoSchemaStrategy,
>> SkipSchemaUpdateStrategy, ThrowOnPartialOrCreateSchemaStrategy,
>> ThrowOnPartialSchemaStrategy
>> ...
>> 
>> 
>> Thoughts?
>> 
>> Thanks,
>> 
>> mrg
>> 
> 
>

Re: DI Configuration Docs

Posted by Michael Gentry <mg...@masslight.net>.
Maintaining it would be the challenge, especially if you wanted it in
a more readable format.  The best thing I can think of offhand is to
add a few DI documentation-specific annotations that we then used to
produce the documentation.

I have no objections linking to the source (although there'd probably
be a different link for 3.1 vs 3.2) or suggesting to use Open Type
"ServerModule" in Eclipse to view the source code (that's my usual
hammer).

mrg


On Wed, Oct 1, 2014 at 11:07 AM, Andrus Adamchik <an...@objectstyle.org> wrote:
> I have no objection to better documenting individual important services, but maintaining a text version of ServerModule is probably a losing battle. I'd say we should better highlight this link:
>
> https://github.com/apache/cayenne/blob/master/cayenne-server/src/main/java/org/apache/cayenne/configuration/server/ServerModule.java#L117
>
> We are doing it already, but probably not explicitly enough:
>
> Cayenne Guide, page 61: "While we describe some of them in the following sections, the best way to get a full list is to check the source code of the Cayenne version you are using and namely look in org.apache.cayenne.configuration.server.ServerModule - the main built-in module in Cayenne."
>
> IMO this approach is one way to strike a balance between providing useful information and overburdening documentation with fine details of many exotic services.
>
> Andrus
>
> On Oct 1, 2014, at 5:41 PM, Michael Gentry <mg...@masslight.net> wrote:
>> I think the DI documentation should include a table/list of all the
>> configurable elements that are available.
>>
>> For example, when I was trying to fix my unit tests to override a
>> value in the model, I had to go digging through the source code to
>> come up with:
>>
>> binder.bind(SchemaUpdateStrategy.class).to(CreateIfNoSchemaStrategy.class);
>>
>> If the documentation had a table/list of available options, it would
>> be easier for people to find and configure.  For example:
>>
>> Interface: SchemaUpdateStrategy
>> Default Implementation: Cayenne Model Value
>> Supplied Impementations: CreateIfNoSchemaStrategy,
>> SkipSchemaUpdateStrategy, ThrowOnPartialOrCreateSchemaStrategy,
>> ThrowOnPartialSchemaStrategy
>> ...
>>
>>
>> Thoughts?
>>
>> Thanks,
>>
>> mrg
>>
>

Re: DI Configuration Docs

Posted by Andrus Adamchik <an...@objectstyle.org>.
I have no objection to better documenting individual important services, but maintaining a text version of ServerModule is probably a losing battle. I'd say we should better highlight this link:

https://github.com/apache/cayenne/blob/master/cayenne-server/src/main/java/org/apache/cayenne/configuration/server/ServerModule.java#L117

We are doing it already, but probably not explicitly enough:

Cayenne Guide, page 61: "While we describe some of them in the following sections, the best way to get a full list is to check the source code of the Cayenne version you are using and namely look in org.apache.cayenne.configuration.server.ServerModule - the main built-in module in Cayenne."

IMO this approach is one way to strike a balance between providing useful information and overburdening documentation with fine details of many exotic services. 

Andrus

On Oct 1, 2014, at 5:41 PM, Michael Gentry <mg...@masslight.net> wrote:
> I think the DI documentation should include a table/list of all the
> configurable elements that are available.
> 
> For example, when I was trying to fix my unit tests to override a
> value in the model, I had to go digging through the source code to
> come up with:
> 
> binder.bind(SchemaUpdateStrategy.class).to(CreateIfNoSchemaStrategy.class);
> 
> If the documentation had a table/list of available options, it would
> be easier for people to find and configure.  For example:
> 
> Interface: SchemaUpdateStrategy
> Default Implementation: Cayenne Model Value
> Supplied Impementations: CreateIfNoSchemaStrategy,
> SkipSchemaUpdateStrategy, ThrowOnPartialOrCreateSchemaStrategy,
> ThrowOnPartialSchemaStrategy
> ...
> 
> 
> Thoughts?
> 
> Thanks,
> 
> mrg
>