Martijn Dashorst created WICKET-7180:
----------------------------------------
Summary: User manual claude review
Key: WICKET-7180
URL: https://issues.apache.org/jira/browse/WICKET-7180
Project: Wicket
Issue Type: Improvement
Reporter: Martijn Dashorst
h1. Apache Wicket User Guide Review
The user guide consists of *221 AsciiDoc files* across *30+ chapters*, totaling
a substantial reference work. Here are the findings organized by severity.
----
h2. 1. CRITICAL: Guide-Wide Issues
h3. The guide says "Wicket 9.x" but lives in the 10.x codebase
* {{single.adoc:1}} -- Title reads {{= Wicket 9.x Reference Guide}}
* {{introduction.adoc:30}} -- Still says "this guide is based on Wicket 9"
* The *javax to jakarta namespace migration* (the single biggest Wicket 10.x
change) is never mentioned anywhere
h3. Dead URLs used throughout the entire guide
|| URL || Issue || Used in ||
| {{https://wicket-guide.herokuapp.com/}} | Heroku free tier shut down Nov 2022
| {{single.adoc:13}}, {{howToSource.adoc:2}}, and every
\{{wicket_tutorial_examples_url}} reference |
| {{http://examples9x.wicket.apache.org}} | HTTP not HTTPS, 9x-specific |
{{single.adoc:12}} |
| {{http://code.google.com/p/google-guice/}} | Google Code shut down 2016 |
{{jee.adoc:10}} |
| {{https://ci.apache.org/projects/wicket/apidocs/9.x/...}} | ci.apache.org is
dead | {{keepControl_9.adoc:42}} |
| {{http://wicketinaction.com}} | Likely dead/parked domain |
{{introduction.adoc:5}} |
| {{http://www.wicket-library.com/...}} | Dead domain |
{{wicketstuff_5.adoc:42}} |
| {{http://docs.spring.io/spring/docs/3.0.x/...}} | Ancient Spring 3 docs (2
occurrences) | {{testingspring_2.adoc}} |
| {{http://java.sun.com/...}} | Legacy Sun URLs | {{modelsforms_6.adoc}},
{{i18n_2.adoc}} |
| {{http://www.oracle.com/.../jce-7-download-...}} | Java 7 JCE page, obsolete
since Java 9 | {{security_4.adoc:18}} |
| {{http://plugins.netbeans.org/plugin/3586/wicket-1-4-support}} | Plugin for
Wicket *1.4* | {{maven_2.adoc:107}} |
| {{http://code.google.com/p/wicketforge/}} | Google Code dead |
{{maven_2.adoc:111}} |
Additionally, *dozens of HTTP links* should be HTTPS: wikipedia.org, spring.io,
jcp.org, owasp.org, objenesis.org, wicket.apache.org, etc.
----
h2. 2. HIGH: Code That Won't Compile
|| File || Line || Issue ||
| {{advanced_1.adoc}} | 33/37 | Variable {{asterisktHtml}} vs {{asteriskHtml}}
-- name mismatch |
| {{advanced_6.adoc}} | 38 | {{NoCacheMarkupPanel}} missing {{implements
IMarkupResourceStreamProvider}} |
| {{bestpractices_1.adoc}} | 67 | {{regmodel}} should be {{regModel}} (case
mismatch) |
| {{bestpractices_1.adoc}} | 104 | Missing closing {{)}} for {{add()}} |
| {{bestpractices_5.adoc}} | 58 | {{startWith()}} should be {{startsWith()}} |
| {{keepControl_5.adoc}} | 72-77 | Variable {{fragment}} declared twice in same
scope |
| {{layout_3.adoc}} | 35 | {{<html>}} instead of {{</html>}} (closing tag) |
| {{modelsforms_2.adoc}} | 51-54 | {{flatMap}} example: {{() ->
targetPerson::getName}} won't compile |
| {{modelsforms_2.adoc}} | 70 | {{assertEquals}} missing closing {{)}} and
{{.getObject()}} |
| {{modelsforms_5.adoc}} | 56 | {{DropDownChoice<String>}} but model is
{{<Person>}} -- type mismatch |
| {{forms2_3.adoc}} | 11 | Extra closing parenthesis |
| {{forms2_11.adoc}} | 142 | {{ListModel<String>}} but data is {{List<Person>}}
|
| {{forms2_12.adoc}} | 73 | Same String/Person type mismatch |
| {{resources_3.adoc}} | 117/122 | Missing closing {{)}} in {{Source}}
constructor |
| {{resources_16.adoc}} | 13 | {{add(vide)}} -- should be {{add(video)}} |
| {{requestProcessing_4.adoc}} | 131 | {{public static MetaDataApp extends
WebApplication}} -- missing {{class}} keyword |
| {{security_3.adoc}} | 55-58 | {{public class HttpsPage implements IMarker}}
-- must extend {{WebPage}} |
| {{security_5.adoc}} | 51 | {{ResourseIsolationRequestCycleListener}} -- typo
in class name (compile error) |
| {{urls_2.adoc}} | 8 | {{BookmarkablePageLink}} constructor missing required
{{id}} parameter |
----
h2. 3. HIGH: Factual Errors / Removed APIs
|| File || Issue ||
| {{requestProcessing_5.adoc}} | {{IProvider<IExceptionMapper>}} no longer
exists -- replaced by {{Supplier<IExceptionMapper>}} |
| {{urls_3.adoc:64-71}} | {{setDefaultBeforeDisabledLink()}} /
{{setDefaultAfterDisabledLink()}} -- *removed* from Wicket |
| {{forms2_5.adoc:70}} | Generated markup shows {{IFormSubmitListener}} --
*removed* in Wicket 9 |
| {{internals/pagestoring.adoc:22}} | References {{IDataStore}} -- *no longer
exists*, replaced by {{IPageStore}} |
| {{redirects.adoc:18-52}} | References {{popBufferedResponse}} and
{{BufferedHttpServletResponse}} -- *don't exist* in modern Wicket |
| {{http2push_1.adoc}} + {{monitoring_1.adoc}} | Maven coordinates
{{org.apache.wicket.experimental.wicket8}} with {{0.X-SNAPSHOT}} -- *wrong* for
9.x |
| {{ajax_3.adoc:114}} | {{Duration.seconds(3)}} uses deprecated Wicket
Duration; should be {{java.time.Duration.ofSeconds(3)}} |
| {{modelsforms_3.adoc}} | {{LambdaModel}} shown with public constructor --
it's actually *private* (must use {{of()}} factory) |
| {{modelsforms_3.adoc:56}} | PropertyResolver at
{{org.apache.wicket.util.lang}} -- moved to
{{org.apache.wicket.core.util.lang}} |
| {{modelsforms_5.adoc}} + {{forms2_11.adoc}} | Interface {{IChoiceRender}} --
actual name is {{IChoiceRenderer}} |
| {{internals/pagestoring.adoc:2}} | Wrong package:
{{org.apache.wicket.request.mapper.IPageSource}} (should be
{{...core.request.mapper...}}) |
| {{requestProcessing_3.adoc:65}} | Prose says {{onBeforeRequest}} but actual
method is {{onBeginRequest}} |
| {{helloWorld_2.adoc:14}} | {{org.apache.wicket.Protocol.http.WicketFilter}}
-- capital "P" typo |
| {{whyLearn_4.adoc:6}} | Says issues go to Apache JIRA -- *Wicket migrated to
GitHub Issues* |
| {{jee_1.adoc:29}} | Uses {{@ManagedBean}} -- *removed* in Jakarta EE 11,
deprecated long before |
| {{testingspring_2.adoc:127}} | {{addComponentInstantiationListener()}} --
method *doesn't exist*; should be
{{getComponentInstantiationListeners().add()}} |
| {{testingspring_2.adoc:10}} | {{@TransactionConfiguration}} -- *removed* from
Spring 5.x |
| {{wicketstuff_4.adoc}} | Entire section describes defunct *Google Image
Charts API* (shut down years ago) |
| {{security_8.adoc:19}} | Recommends {{X-XSS-Protection}} header --
*deprecated and removed* from modern browsers |
----
h2. 4. MEDIUM: Outdated Content
h3. javax vs jakarta (affects Wicket 10.x)
* {{requestProcessing_4.adoc:31}} -- explicitly says
{{javax.servlet.http.HttpSession}}
* {{jee_3.adoc}} -- {{@Inject}} / {{@Named}} from {{javax.inject}} (now
{{jakarta.inject}})
* {{modelsforms_7.adoc:76}} -- says {{javax.persistence.EntityManagerFactory}}
* {{forms2_4.adoc}} -- references "JSR 303" throughout (now Jakarta Bean
Validation)
* {{resources_14.adoc:40}} -- {{javax.servlet.ServletContext}}
* {{nativewebsockets_2.adoc}} -- artifact {{wicket-native-websocket-javax}},
class {{JavaxWebSocketFilter}}
* {{security_4.adoc:18}} -- references JCE Unlimited Strength for Java 7
(default since Java 9)
h3. Ancient version references
Many files reference features as "new in Wicket 6.x" or "7.x":
* {{advanced_3.adoc}} -- "Starting from version 1.5"
* {{versioningCaching_2.adoc:74}} -- "Starting from version 1.5"
* {{componentQueueing.adoc:3}} -- "new feature in Wicket 7"
* {{helloWorld_4.adoc:53}} -- "Since Wicket 8 is built on Java 8"
* {{forms2_4.adoc:2}} -- "since version 6.4.0...6.14.0"
* {{ajax_5.adoc:4}} -- "Starting from version 6.0"
* {{http2push.adoc:2}} -- "With Wicket 8.0.0-M2"
* {{wicketstuff_1.adoc:26}} -- uses {{8.0.0-SNAPSHOT}} as example version
* Plus ~15 more instances
h3. Outdated technology references
* {{jsintegration_1.adoc:6}} -- YUI library (discontinued 2014)
* {{ajax_2.adoc:136}} -- "classic look & feel of Windows XP"
* {{componentLifecycle.adoc:2}} -- "Just like applets and servlets" (applets
removed in Java 17)
* {{jee.adoc:10}} -- mentions JBoss Seam (dead since ~2012), OpenEJB (now
Apache TomEE)
* {{monitoring_2.adoc}} -- Graphite setup uses Python 2, Django 1.5, Twisted 11
(all ancient/EOL)
* {{testing.adoc:5}} -- says JUnit version is "4.x" but Wicket 10 uses JUnit 5
* {{resources_10.adoc:42}} -- {{com.sun.syndication}} package (now
{{com.rometools}})
* {{nativewebsockets.adoc:8}} -- lists Jetty 7.5+, Tomcat 7.0.27+ as supported
h3. Missing content for modern Wicket
* No coverage of the *Wicket 10.x / Jakarta EE migration* -- the single biggest
change for users
* No mention of *Java 17+ requirement* for Wicket 10.x
* Module table ({{helloWorld_1.adoc}}) missing {{wicket-cdi}},
{{wicket-native-websocket}}, {{wicket-migration}}, {{wicket-tester}}
* {{forms2_3.adoc}} -- ConverterLocator missing {{java.time}} converters
(LocalDate, LocalDateTime, etc.)
* Testing chapter has no JUnit 5 examples
* Security chapter missing: XSS protection, session fixation, SameSite cookies,
serialization security
* No mention of {{ModalDialog}} (replacement for deprecated {{ModalWindow}})
----
h2. 5. LOW: Spelling, Grammar & Typos
h3. Recurring patterns
* *"instanciation"* instead of "instantiation" -- {{bestpractices_6.adoc}},
{{bestpractices_10.adoc}}, {{bestpractices_12.adoc}}
* *"informations"* instead of "information" -- {{layout_1.adoc}},
{{i18n_1.adoc}}, {{requestProcessing_3.adoc}}, {{modelsforms_7.adoc}}
* *Raw types* throughout code examples -- {{new Model()}}, {{new
PropertyModel(...)}}, {{new CompoundPropertyModel(...)}} without generics
h3. Individual typos
|| File || Typo || Correction ||
| {{whyLearn.adoc:4}} | "ask ourself" | "ask ourselves" |
| {{keepControl_1.adoc:6}} | "sensibly deteriorate" | "noticeably deteriorate" |
| {{componentLifecycle_1.adoc:9}} | "facultative" | "optional" |
| {{componentLifecycle_1.adoc:18}} | "we didn't covered" | "we haven't covered"
|
| {{componentLifecycle_6.adoc:4}} | "move a the detached" | "move to the
detached" |
| {{layout_2.adoc:2}} | "Wouldn't be great" | "Wouldn't it be great" |
| {{layout_2.adoc:45}} | "iterate thought" | "iterate through" |
| {{modelsforms_4.adoc:99}} | "TextFiled" | "TextField" |
| {{modelsforms_7.adoc:78}} | "to loose these" | "to lose these" |
| {{modelsforms_8.adoc:13}} | "ComponetTwoModels" | "ComponentTwoModels" |
| {{forms2_4.adoc:2}} | "it has became" | "it has become" |
| {{forms2_9.adoc:14}} | "wildly adopted" | "widely adopted" |
| {{urls_6.adoc:6,96}} | "WepApplication" (2x) | "WebApplication" |
| {{urls_6.adoc:163}} | "IPage ParametersEncoder" | "IPageParametersEncoder" |
| {{nativewebsockets_2.adoc:89}} | "enviroment" | "environment" |
| {{nativewebsockets_2.adoc:90}} | "implemetation" | "implementation" |
| {{security_6.adoc:11}} | "conveniant" | "convenient" |
| {{jee_4.adoc:16}} | "depencencies" | "dependencies" |
| {{resources_3.adoc:33}} | "Jave Code" | "Java Code" |
| {{resources_8.adoc:26}} | "JavaScricpt" | "JavaScript" |
| {{resources_15.adoc:4}} | duplicate "setJavaScriptCompressor" | second should
be "setCssCompressor" |
| {{resources_16.adoc:2}} | "FileSystemResourceRenference" |
"FileSystemResourceReference" |
| {{i18n_2.adoc:42-43}} | "ISO 8859-11" (2x) | "ISO 8859-1" |
| {{bestpractices_2.adoc}} | "formular" | "form" |
| {{bestpractices_3.adoc}} | "unneccessary", "the the" | "unnecessary", "the" |
| {{bestpractices_12.adoc}} | "easliy" | "easily" |
| {{bestpractices_15.adoc}} | "seperate" | "separate" |
| {{bestpractices_16.adoc}} | "Crtl" | "Ctrl" |
| {{wicketstuff_6.adoc:8}} | "pubblic" | "public" |
| {{wicketstuff_6.adoc:80}} | "construcor" | "constructor" |
| {{contributing.adoc:14}} | folder path "asciidoctor" | "asciidoc" |
| {{resources_8.adoc:56-57}} | {{<header>}} tag | {{<head>}} tag |
| {{advanced_3.adoc:37}} | "InterComponetsEventsExample" |
"InterComponentsEventsExample" |
| {{advanced_6.adoc:4,34}} | "dynamical generate" (2x) | "dynamically generate"
|
| {{ajax_2.adoc:32}} | "overriden" | "overridden" |
| {{ajax_2.adoc:164}} | "for the three" | "for the tree" |
| {{ajax_3.adoc:123}} | "statelss" | "stateless" |
| {{jsintegration_2.adoc:52}} | {{http://jqueryui.com/ datepicker}} (space in
URL) | {{http://jqueryui.com/datepicker/}} |
| {{jsintegration_2.adoc:103}} | "renderHeader" in prose | "renderHead" (method
name) |
h3. Wrong \[source,...] tags
Multiple files use {{\[source,java]}} for non-Java content:
* JavaScript blocks: {{nativewebsockets_3.adoc}}, {{jsintegration_2.adoc}}
* HTML blocks: {{layout_4.adoc}}, {{componentQueueing_1.adoc}},
{{pagestoring.adoc}}
* XML blocks: {{monitoring_1.adoc}}, {{monitoring_2.adoc}},
{{monitoring_4.adoc}}
* Shell commands: {{howToSource.adoc}}
----
h2. Summary
The user guide is a *valuable and comprehensive resource* but it has
accumulated significant technical debt:
# *~19 code examples that won't compile* (type mismatches, missing params,
typos in identifiers)
# *~18 references to removed/renamed APIs* that no longer exist in modern Wicket
# *~12 dead URLs* and dozens more that should use HTTPS
# *No coverage of the Wicket 10.x / Jakarta EE migration* -- the single biggest
change for users
# *~40+ spelling/grammar errors* with some patterns repeating across files
# *Outdated technology references* (YUI, Windows XP, Python 2, JUnit 4, Wicket
1.5/6.x feature introductions)
The guide would benefit most from: (1) fixing compile errors in code examples,
(2) updating removed API references, (3) replacing dead URLs, and (4) adding a
Jakarta migration section for Wicket 10.x users.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
