[External] : Re: Javadoc for API

[Jorn Vernee]

Note that --dump-includes already exists, and generates a flat list of 
`--include-XXX` options that can be passed back to jextract (not JSON). 
You would need to parse these options manually. I think the format would 
be relatively stable, only needing to change if we change the command 
line options.

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

Yes, this changed as part of: https://github.com/openjdk/jextract/pull/255

It looks like the Logger class that was added is not part of the public 
API, so right now I don't think there's a way to capture those errors 
aside from capturing and parsing them from the output.

Jorn

On 30-1-2025 14:06, Nir Lisker wrote:
> 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/9942c47d/attachment.htm>