Subject: Re: PL/Java new build plugin
To: Kartik Ohri <kartikohri13@gmail.com>
References: 
 <CAASLQ4Mva7dAXiS_c9OLhV4VzNHF=XNKJosuS5gtZTB6b4TW1Q@mail.gmail.com>
 <5F18C58F.8060204@anastigmatix.net>
 <CAASLQ4NkEDo-UAmqSwUTkCdMu+3WedKCfva5gzNTC45YcWEwNA@mail.gmail.com>
 <5F19C36C.70905@anastigmatix.net>
 <CAASLQ4M_f8cYmxfX5Jqgm9AJHsX62_Cc5pvniXjer4jAZOMOBQ@mail.gmail.com>
 <CAASLQ4Pcp24U3rkWkGvcidTfCLQEsAE1it7b3Sr_uNbgO3P9kA@mail.gmail.com>
 <5F1C6F06.2020809@anastigmatix.net> <5F1CE067.2060107@anastigmatix.net>
 <CAASLQ4OZyt3QL5ZCH0JQyZvuOWTEOgOpko4fC+DPDXgJV0HuPw@mail.gmail.com>
 <5F1F88E0.2050305@anastigmatix.net>
 <CAASLQ4PyG-YvKUTYdqfuQW8yGL+t_93b1i2CMTusoYHbZ0ZTMg@mail.gmail.com>
 <CAASLQ4MDUNP_4BAqK7ZtxtqG7ErH6skMKbNRvL0vE58wdRVxiQ@mail.gmail.com>
 <5F20E585.6010703@anastigmatix.net>
 <CAASLQ4PEcB-Rf1-vFtKCLNxVC6YZsSrzRUd_5TXZsPJp74vvcg@mail.gmail.com>
 <CAASLQ4M1dg+z+J44g77cvzSe3y8q01kWbvCcgoyNzA0j=apfAA@mail.gmail.com>
 <5F22DF79.2090701@anastigmatix.net>
 <CAASLQ4POay=ZLsdOb02n6NqwTn7MGyyWQprcCEo2Wm6Y6rStEw@mail.gmail.com>
Cc: pljava-dev@lists.postgresql.org
From: Chapman Flack <chap@anastigmatix.net>
Message-ID: <5F230337.3040406@anastigmatix.net>
Date: Thu, 30 Jul 2020 13:28:23 -0400
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.0
MIME-Version: 1.0
In-Reply-To: 
 <CAASLQ4POay=ZLsdOb02n6NqwTn7MGyyWQprcCEo2Wm6Y6rStEw@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 07/30/20 11:37, Kartik Ohri wrote:
>  To clarify, I have exposed the instance and written the snippet using
> Doxia sink to generate the html file in the pom.xml. I meant that we could
> factor out the sink part in a default method in an interface and expose it
> to javascript for providing an alternate implementation if wanted. It is
> this part I am unsure of how to do.

Ah, got it.

Right now, nothing is jumping out at me as an obvious way to supply a
default implementation for a generic report. (Not even thinking of the
mechanics of doing it just now, only the wider question of what such a
default method would do.) I would say that's a bit of refactoring that
isn't needed now, but some future day if there has been some experience
using the mojo to script both Javadoc and some other sort of report,
what turns out to be common between those uses might supply ideas for
a refactoring then.

I am a little disappointed that the Sink methods return void instead of
the sink, so they can't be used fluently; if I were looking for one
simple way to make the script snippet end up prettier, I might consider
writing a wrapper class that's like Sink but with methods returning this,
so the script can be written in a fluent style.

However, writing such a wrapper for an interface with nearly 200 methods
sounds like a job for an extremely boring rainy day, definitely not a
priority for right now.

If I were writing such a wrapper, I might also consider wrapping each
foo()/foo_() pair of start/end methods as a single method that takes
a lambda generating the content inside, so misnesting would not be
possible. (If I'm not mistaken, there's a bit of misnesting in your
snippets, sectionTitle_ before link_ ... a nicer API would leave no
need to think about that.)

But probably there are better areas to polish right now. A generic
scripting mojo can't really know "you're going to want the jar path
for a dependency named pljava-api, I'll put that in a variable for you";
it just needs to expose some way to get the project object so the
script can do such lookups.

I am probably also passing the Javadoc -d option the wrong way
(hardcoding ${basedir}/target/site/apidocs). Probably should just
tack on "apidocs" to report.getReportOutputDirectory() (using something
like toPath().resolve("apidocs") so the tacking-on is platform-aware.

Likewise, what I was passing to -encoding and -docencoding
should probably come from report.getInputEncoding() and
report.getOutputEncoding(), respectively. All that should
be straightforward with the report instance exposed.

Hmm, but those encoding methods are protected; the script might not
have access. Accessible versions might have to be supplied.

Regards,
-Chap