[
https://issues.apache.org/jira/browse/WICKET-7180?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18072958#comment-18072958
]
ASF GitHub Bot commented on WICKET-7180:
----------------------------------------
dashorst opened a new pull request, #1424:
URL: https://github.com/apache/wicket/pull/1424
After a full review of the user guide, claude suggested these edits to
improve the language, links, and code examples to ensure the docs are
up to our Wicket 10.x standards.
> User manual claude review
> -------------------------
>
> Key: WICKET-7180
> URL: https://issues.apache.org/jira/browse/WICKET-7180
> Project: Wicket
> Issue Type: Improvement
> Reporter: Martijn Dashorst
> Priority: Minor
>
> 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)
