Create account / Log in

A possible side-project

Discussion area for the development team.

Moderators: uckelman, Tim M

A possible side-project

Postby Cattlesquat » July 23rd, 2020, 9:13 pm

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.

Brian
User avatar
Cattlesquat
 
Posts: 953
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: A possible side-project

Postby Flint1b » July 23rd, 2020, 11:34 pm

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.
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: A possible side-project

Postby uckelman » July 23rd, 2020, 11:55 pm

Thus spake Cattlesquat:
> 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.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 9014
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: A possible side-project

Postby Cattlesquat » July 24th, 2020, 12:42 am

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.
* Happy to consult on profiling.

Brian
User avatar
Cattlesquat
 
Posts: 953
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: A possible side-project

Postby Flint1b » July 24th, 2020, 1:25 am

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.
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: A possible side-project

Postby Cattlesquat » July 24th, 2020, 1:53 am

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!

Brian
User avatar
Cattlesquat
 
Posts: 953
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: A possible side-project

Postby Cattlesquat » July 24th, 2020, 2:46 am

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).

Brian
User avatar
Cattlesquat
 
Posts: 953
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: A possible side-project

Postby Cattlesquat » July 24th, 2020, 3:04 am

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.
User avatar
Cattlesquat
 
Posts: 953
Joined: December 2nd, 2019, 4:57 pm
Location: Baltimore, Maryland, USA

Re: A possible side-project

Postby Brent Easton » July 24th, 2020, 3:15 am

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.).
User avatar
Brent Easton
 
Posts: 3229
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Re: A possible side-project

Postby Flint1b » July 24th, 2020, 3:37 am

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 :(

Asciidoc otoh, have a look at the PR that is coming up in a few minutes :D
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: A possible side-project

Postby Brent Easton » July 24th, 2020, 3:45 am

AsciiDoctor?

Ha! beat me to it.
User avatar
Brent Easton
 
Posts: 3229
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Re: A possible side-project

Postby Flint1b » July 24th, 2020, 3:46 am

I love this already, github can even render the Asciidoc file, look at this: https://github.com/yanlyub/vassal/blob/ ... guide.adoc

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 look at how the headings have fixed link URLs e.g. https://github.com/yanlyub/vassal/blob/ ... er-to-peer

Telling someone to RTFM will be taken to a whole new level when we can link them right into the code of the userguide on github.
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: A possible side-project

Postby Flint1b » July 24th, 2020, 3:56 am

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.
User avatar
Flint1b
 
Posts: 461
Joined: May 19th, 2020, 12:27 am
Location: Colonia Agrippina

Re: A possible side-project

Postby Brent Easton » July 24th, 2020, 4:03 am

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.
User avatar
Brent Easton
 
Posts: 3229
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Re: A possible side-project

Postby uckelman » July 24th, 2020, 10:38 am

Thus spake Flint1b:
> 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.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 9014
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Next

Return to Developers

Who is online

Users browsing this forum: No registered users and 3 guests

cron