Consider storing documentation in Javadoc/Github?

FasterXML / woodstox

The gold standard Stax XML API implementation. Now at Github.

Apache License 2.0

228 stars 83 forks source link

Consider storing documentation in Javadoc/Github? #140

Open buko opened 2 years ago

buko commented 2 years ago

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

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 commented 2 years ago

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 commented 3 days ago

@cowtowncoder I could possibly edit Wiki pages

cowtowncoder commented 2 days ago

@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 commented 1 day ago

@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) ❓

cowtowncoder commented 18 hours ago

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 commented 3 hours ago

@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?