A possible side-project that I might be just crazy enough to embark upon: there are large parts of our code that currently appear to my eye to be… “lightly” commented. Like especially things like the piece traits and stuff like that. And I might be interested in going through there and trying to “javadoc them up” a bit better and comment some stuff in the flow that I think might it more approachable to newcomers (as a recent newcomer myself).
Does that sound… good? Or would a bunch of comments be annoying?
If I got going on this I’d probably (surely) have the occasional question.
From a build management perspective yes YES the javadocs badly need fixing, I had to turn all checks off to get it to build a javadoc-jar package. And since we are headed towards giving module designers a maven dependency, their maven will pull that javadoc package to get popups with our javadoc describing our classes, methods and fields.
The javadoc tool is actually very strict and expects proper (non-empty) javadoc above all classes and public methods, explanation of all method parameters, why/how each of the explicit exceptions could be thrown.
A possible side-project that I might be just crazy enough to embark
upon: there are large parts of our code that currently appear to my eye
to be… “lightly” commented. Like especially things like the piece
traits and stuff like that. And I might be interested in going through
there and trying to “javadoc them up” a bit better and comment some
stuff in the flow that I think might it more approachable to newcomers
(as a recent newcomer myself).
Does that sound… good? Or would a bunch of comments be annoying?
If I got going on this I’d probably (surely) have the occasional
question.
Improving the javadoc might be useful. I think going over the regular
documentation and making sure it corresponds to 3.3 would be more useful,
but I recognize that might not be your thing.
Also useful would be profiling some modules and finding out what is slow
right now. Then you could make a start at making those things faster.
Both of those things I expect would have more impact than fixing the
javadoc.
So of those three projects (javadocs, regular docs, profiling), I’m probably “currently best suited for” the two documentation ones. I’ve actually started lightly adding to the regular documentation as I’ve been checking in PR’s, and I’ve had a bit of an itch to improve it more, so I’m happy to go through some of that. I’m also have several TotallyUnauthorized ongoing code projects that are leading me around the codebase which is how I got interested in the javadocs.
Meanwhile I suspect Yan is currently much better positioned than me for profiling, apart from maybe as a heavy duty module designer I do have some, shall we say, “instinctive feels” for where we could use some work. Or I’d be happy to be his module-designer sidekick in such an undertaking. I will certainly agree that e.g. GKC’s that ran faster would make a bigger quality-of-life improvement for Literally Everyone Involved than almost anything else I could imagine.
SO… in addition to my usual spew of PR’s (and perhaps to keep them to a dull roar), I will also:
Take a more “proactive” look at the regular documentation, starting with the htm’s in the ReferenceManual section.
Probably make some “javadoc-ing” PRs when I get in the mood.
Do we want to convert the userguide and/or the /doc/ReferenceManual to something diffable, preferably AsciiDoc, and create the html pages and/or pdf documents during the build?
And the html rendering, we could embed JavaFX into the application and use it’s modern web rendering engine instead of Swing’s html renderer, it won’t be too hard to implement, I already managed to get JavaFX running in a JPanel of the PlayerWindow.
Probably. “But definitely not yet” (at least not yet for the doc/ReferenceManual). Partially because I have several doc/ReferenceManual “.htm” files in my pre-existing PR’s, so I’d want those PR’s to all clear before we unglue their basis for existing. Likewise the new ones I started writing tonight in response to this thread.
BUT the actual texts and pictures are probably pretty independent of the eventual format changes you’d be applying there, so if you have some method for mass-slorping them all into a new format then any new text & pngs I’d put in should be fine, right?
OR… if it’s important to do the conversion before undertaking a big doc project, then that means I should stop doing it right now, and we wait until my .htm-laden PR’s clear and then begin with the big convert-over. Let me know what you think.
MEANWHILE: UserGuide by all means convert away immediately, as far as I’m concerned. I was already sort of dreading having to confront whatever format that’s in, so if it got into diffable format etc etc but could then still be “generated all pretty” when we needed to e.g. during the build process or whatever, then HALLELUJAH!
Hooooo boy and do I need to standardize some terminology in traits. Sometimes it’s called a "Key Command: " (best outcome), but sometimes it’s a "Keyboard Command: " and sometimes it’s a "Keystroke: ". Similarly sometimes the context menu text is called “Menu text”, sometimes “Menu Command”, sometimes just “Command”, etc, etc.
I will probably work my way through the trait code turning the various key command names uniformly into "Key Command: ". Which of course in turn means new screenshots in the ReferenceManual.
And when I do javadocs I’m going to make sure that every decorator definition has its “Trait” name front and center at the top of the file. (e.g. Obscurable == Mask, Immobilized == Does not stack, etc, etc).
SAAAAAAAAAAAAAAAY… any chance while I’m embarking on a “documentation revamp” that you guys could hook me up with a “moderation bypass” on the Wiki? 'Cause there’s stuff I could try to keep consistent between them but right now it’s like trying to carry on a conversation with someone on 2-day time delay.
I think there is a lot of value in having one central representation of our on-line Module Editor help pages and images, from which we can generate
a) Module editor help pages
b) Wiki or Web version of pages
c) A combined PDF version of same.
Asciidoc sounds great and Pandoc should make a decent attempt of converting our current pages, but interestingly, there seem to be tools to convert from mediaWiki to Asciidoc, but not Asciidoc to mediaWiki.
Brian, on another issue, you will find that many of the screen snaps of trait configs are now out of date, and the consistency is variable (some Windows, some Mac etc.).
It’s still a little fucked up from the conversion but all images and 99% of the text made it, I think only half a paragraph was broken, somewhere near an image. The images need some readjusting. Once that is fixed, it will be as good as the old userguide, and from there on it will only get better, with neat formatting options, dynamic injection of current Vassal version number, etc etc.
And this whole “vassal-doc” maven module setup will allow to do the same with the reference manual, we’ll be able to keep the code of it’s html pages in asciidoc format (which is even easier to read & edit for humans than html) and have the maven plugin generate the html pages and also a pdf during the build, before the makefile bakes them into the release packages.
And of course IntelliJ has an Asciidoc editor/renderer plugin
While I am still working out a few shortcuts and sometime find myself stuck looking for a function, I have to say I, am extremely happy that you finally talked me into switching to IntelliJ. Already, after 2 days, I could not go back.
It’s possible to convert from Asciidoc to Docbook, from there using
pandoc to Mediawiki.
But pandoc is… ugh… nice command line tool but it’s Maven plugin is
in version 0.1.6 from 2017
Pandoc is something I think will be great every time I try it, and about
20 minutes in I hit some formatting thing I need that it can’t do in an
obvious way, spend about three hours trying to make it do that, and then
decide it’s not worth the effort and do it in LaTeX instead.
That was my experience as well when I switched a couple years ago. Many companies nowadays realize that it’s a good productivity boost and let their developers use the free Eclipse or buy them a license for the full IntelliJ version.
So… does it still make sense for me to continue assembling documentation updates n the doc/ReferenceManual area as a precursor to The Big AsciiDoc?
I’m assuming there will be some inevitable amount of blood/sweat/tears converting the files over no matter which way we go about it, and that’s fine, I just don’t want to piss directly into the wind. More of a light crosswise mist.
Well you already started, I would say finish up the changes that you wanted to do, and then we will convert them to asciidoc.
I moved the whole /doc folder into a new maven project, I think it’s easiest if we get your PR merged first, then I’ll update my PR and fix possible conflicts.
Looking at all the screenshots in the userguide and the reference manual is like a history lesson in windowed operating systems, there are screenshots from what could be win95 with the traditional black-on-grey “X” buttons, screenshots from XP with its funky circus-style red “X” button, and even screenshots from what looks like “motif” UI on linux
The userguide will need some updating in the requirements and installation areas, it still says “Java 5” needed, also the “useful tools” section reminds of good old multiplayer gaming times with ventrilo and teamspeak. I think the kids nowadays only know discord. Which is actually pretty damn cool. We could replace the whole server/jabber stuff with discord, they offer a very rich API for developers.
Haha yes, there’s a current thread in the Module Design forum where I happened to mention that I was updating the documentation, and he asked if I could please burn the PDF manual as it caused him so much frustration when learning Vassal.
(at least not yet for the doc/ReferenceManual). Partially because I have several doc/ReferenceManual “.htm” files in my pre-existing PR’s, so I’d want those PR’s to all clear before we unglue their basis for existing. Likewise the new ones I started writing tonight in response to this thread.
