[External] : Re: Javadoc for API

[Nir Lisker]

It's probably possible to do, but looks roundabout.

Here is my setup in more detail:
1. A header is given to the application. It calls 'parse' on it to get all
the Declarations.
2. The user can configure which declarations to include in the GUI, and
also the other options such as class name, macros, output dir etc.
3. The 'run' method is called with the arguments generated from the
configuration.

It's all in-memory.

With --dump-includes:
1. A header is given to the application. A JSON file is created.
2. The file is read and parsed to produce the Declarations. Configuring a
JSON parser is already a lot of work for polymorphic sybtyping (all the
types of Declarations). Will jextract provide a parser? What is the format?
Is it stable?
3. Is 2 above.
4. Is 3 above.

So we complicated things by creating a file from which we need to read the
data that would otherwise be given to us directly by 'parse'. At least this
is my understanding.

Speaking of 'parse', I notice that it doesn't throw an exception on a
missing '#include <header.h>' as it used to. Now I only see a printed
error. Has this changed? Is there a way to capture this error somehow so
that the user knows something went wrong?

On Tue, Jan 28, 2025 at 5:06 PM Jorn Vernee <jorn.vernee at oracle.com> wrote:

> > There is no need for a dump.
>
> But, do you think you could do the things you're doing, using
> JextractTool::parse, by using --dump-includes instead?
>
> I'm trying to assess if we even need the API at all, or if we can just
> have the ToolProvider.
>
> Jorn
> On 28-1-2025 15:12, Nir Lisker wrote:
>
> I use
> JextractTool.parse(List<String> arg0, String... arg1)
> to inspect given header files. Then I use
> ToolProvider.run(PrintStream out, PrintStream err, String... args)
> which is not Jextract-specific to run the tool with the user's
> configuration. There is no need for a dump.
>
> I want to release an alpha soon so you'll be able to see how it works.
>
> On Tue, Jan 28, 2025 at 2:28 PM Jorn Vernee <jorn.vernee at oracle.com>
> wrote:
>
>> Hey Nir,
>>
>> The jextract API has been neglected for a while (as you've found).
>> Initially it was a way of avoiding adding many flags to jextract, to do
>> things like filtering, renaming, and other things. The idea being that
>> if users wanted more control of what jextract did, they could use the
>> API. But, now it seems like we're moving in that direction any way, with
>> the JSON based configuration:
>> https://bugs.openjdk.org/browse/CODETOOLS-7903788
>>
>> I think we need to re-asses which use cases the jextract API addresses,
>> and whether using jextract through the ToolProvider interface, with the
>> extended configuration options, is also an option.
>>
>> IIRC your use case is filtering the jextract output, right? Do you think
>> it would be possible to use the ToolProvider interface with a
>> combination of --dump-includes, and automatically generated
>> --include-XXX flags, to achieve the same level of functionality?
>>
>> Jorn
>>
>> On 26-1-2025 08:51, Nir Lisker wrote:
>> > Hi,
>> >
>> > There are several public methods the JextractTool exposes. Please
>> > javadoc to these methods so tool users will know what they do and how
>> > to use them.
>> >
>> > Thanks,
>> > - Nir
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/jextract-dev/attachments/20250130/5a5a165a/attachment-0001.htm>