Link to "how to read this manual" on DSLContext create... and other ambiguous references

[stevesims330]

Many pages reference an instance called "create" such as http://www.jooq.org/doc/3.4/manual/sql-building/sql-statements/insert-statement/. Unfortunately, it's not clear what "create" is, even though it's explained at http://www.jooq.org/doc/3.4/manual/getting-started/the-manual/#N240AB.

A tooltip with a link to "how to read this manual", as suggested in #3151, would help a bit but many people wouldn't guess that an explanation for what "create" means in the documentation would be there.

[lukaseder]

Thanks for your feedback. This has indeed been a point that was brought up frequently in the past. What would be the best way to explain these parts of the manual, according to you?

(we've also contemplated replacing all create references by actual DSL.using(configuration) references, in the past)

[lukaseder]

... another (general) option would be to link references from the code sections to the relevant Javadoc. E.g. a reference in jOOQ 3.4's manual to DSL would link to: www.jooq.org/javadoc/3.4.x/org/jooq/impl/DSL.html, etc.

References to create would then link to the manual's section:
http://www.jooq.org/doc/latest/manual/getting-started/the-manual (although create would need to be stressed more explicitly)

[stevesims330]

I think a link to http://www.jooq.org/doc/3.4/manual/getting-started/the-manual/#N240AB on the word "create" would be fine, though DSLContext create = DSL.using(connection, SQLDialect.ORACLE); might have to stand out better. Maybe it could be in its own black box or something, and the explanatory comments above it could be outside of the black box.

A link to the JavaDoc would be fine too if the JavaDoc has a useful/relevant usage examples involving an instance named create.

[lukaseder]

See also: #3504, #3151

[lukaseder]

See also: http://stackoverflow.com/q/25542514/521799

[lukaseder]

This is in fact covered by #3504