Consider storing documentation in Javadoc/Github?

[buko]

It seems like there's some important documentation about woodstox available at medium.com:

• https://medium.com/@cowtowncoder/configuring-woodstox-xml-parser-basic-stax-properties-39bdf88c18ec
• https://medium.com/@cowtowncoder/configuring-woodstox-xml-parser-stax2-properties-c80ef5a32ef1
• https://medium.com/@cowtowncoder/configuring-woodstox-xml-parser-woodstox-specific-properties-1ce5030a5173

Unfortunately medium.com is commonly blocked in many countries. Developers in such countries can't read these docs... Access to github is generally possible. Could such documentation be moved to github wiki? Another possibility might be javadoc.

[cowtowncoder]

Yes, good idea. If anyone wants to help in form of PRs (for Javadocs) or additions to Wiki (which probably needs me to add access) that'd be great! I can help but probably won't have time to drive this myself.

[winfriedgerlach]

@cowtowncoder I could possibly edit Wiki pages

[cowtowncoder]

@winfriedgerlach LMK if you have access to do so. Also: I give permission for copying of any Medium content I wrote to be added to Wiki, fwtw.

[winfriedgerlach]

@cowtowncoder @buko all right, I added the Medium articles to the Wiki: https://github.com/FasterXML/woodstox/wiki/Configuring-Woodstox-XML-parser

ToDo:

• maybe split in 3 pages? (I'm open for suggestions) ✅
• update links to point to JavaDoc 7.1.x instead of 5.0 ✅
  • update links to point to Java SE 8 instead of 7 (minimum requirement of Woodstox 7.x) ✅
  • update links to point to stax2-api 4.2.2 instead of 4.0.0? where is the JavaDoc? ✅
• update description if needed (e.g., "As of now (November 2024) this feature is NOT YET implemented", or "to be added in Woodstox 5.2") ✅
• add sections for new properties (if any) ✅ (compiled list of new properties, see comment below)

[cowtowncoder]

Excellent, thank you @winfriedgerlach!

I think one page (over 3) is acceptable. Splitting into 3 might be even better eventually.

Otherwise:

• Yes, for javadoc links
• Yes for "not yet implemented" & outdated time refs
• Yes if you (or anyone else) finds missing properties to cover, should add (or create issue outlining omission and I can eventually add)

[winfriedgerlach]

@cowtowncoder OK, I split it in 3 pages (matching the structure on Medium), linked them from the Wiki start page and README.md (see PR #218), updated links to Woodstox 7.1, updated Java SE links to 8, updated description with outdated time refs.

Is there stax2-api 4.2.2 Javadoc online anywhere?

[cowtowncoder]

Right now 4.0 only exists:

https://github.com/FasterXML/stax2-api/wiki

but I'll see if I can add 4.2 (patch shouldn't matter)

[cowtowncoder]

Actually, they do:

https://javadoc.io/doc/org.codehaus.woodstox/stax2-api/4.2.2/index.html

which resolves to

https://javadoc.io/doc/org.codehaus.woodstox/stax2-api/latest/index.html

I updated Wiki with proper links.

[winfriedgerlach]

Great, I updated all links on https://github.com/FasterXML/woodstox/wiki/Configuring-Woodstox-II-%E2%80%90-Stax2-Properties to point to "stax2-api/latest" 👍🏼

[cowtowncoder]

Thank you again @winfriedgerlach !

[winfriedgerlach]

@cowtowncoder as far as I can see, StAX and StAX2 properties have remained stable over the years. For the Woodstox-specific (input) properties, the following could be added to the Wiki:

• P_ALLOW_SURROGATE_PAIR_ENTITIES
• P_MAX_DTD_DEPTH
• P_CUSTOM_INTERNAL_ENTITIES

You could either add these now or just close this ticket please.

[cowtowncoder]

Created #225 for remaining work; closing this issue.