You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@daffodil.apache.org by Mike Beckerle <mb...@tresys.com> on 2018/02/22 17:30:46 UTC
more scaladoc needed?
I was looking at our javadoc and scaladoc for rc2, as linked from here:
https://daffodil.apache.org/releases/2.1.0/
My mental experiment was to write my own Java InfosetOutputter (something requested by folks at AFRL) to directly output RDF triples from a parse.
This turns out to be impossible, as our scaladoc for InfosetOutputter, does not allow one to drill into the DISimple, DIComplex or DIArray classes/traits of the arguments to the InfosetOutputter method calls.
Do we provide the general scaladoc tree for all of daffodil anywhere online other than in a javadoc archive that can be pulled as a managed dependency?
Re: Daffodil-1909 (JAPI/SAPI thing)
Posted by Steve Lawrence <sl...@apache.org>.
The JAPI/SAPI are essentially just wrappers around internal things. This
is necessary for the Java side of things since some Scala concepts are
difficult to represent in Java (e.g. enums) so there's kindof a mapping
from scala land to java land. The SAPI mimics the Java API for consistency.
The two are very very very similar, but has a few main differences.
The first is making for a Java friendly API. For example, as mentioned
earlier, the JAPI includes Java enums for things like ValidationMode and
Logging. There are also a couple places where the Java API will return a
java.util.List whereas the Scala API will return a scala Seq.
The other issue that prevents merging the two is that I found it
difficult to create ScalaDoc that would also create JavaDoc. Use use a
plugin to convert scaladoc to javadoc, and it works fairly well, but
some valid scaladoc just doesn't convert to Javadoc well, so the
scaladoc needs to be input different than normal. Also things like
example code needs to be in java vs scala, which makes things trickier.
- Steve.
02/23/2018 09:32 AM, Mike Beckerle wrote:
> Steve,
>
> At one time there was a issue with the JAPI/SAPI design.... redundant stuff there, awkward to add things, etc.
> In glancing at it the other day it looked unfamiliar to me. Was this fixed, or is that still outstanding work we need to do? If so we should add comment to Daffodil-1909 to that effect, or link it to other JIRA tickets about that issue.
>
> ...mikeb
>
> ________________________________
> From: Steve Lawrence <sl...@apache.org>
> Sent: Thursday, February 22, 2018 1:22:00 PM
> To: dev@daffodil.apache.org; Mike Beckerle
> Subject: Re: more scaladoc needed?
>
> We do not currently provide the general scaladoc tree for all of
> daffodil online anywhere. And I'm hesitant to provide that since I view
> anything not in the daffodil-japi or daffodil-sapi subprojects as
> internal and subject to change (i.e. not suitable for an API).
>
> I think DAFFODIL-1909 that you just added is the right approach to solve
> this. We should add an abstract class/trait that provides a minimal and
> maintainable interface to the internals of the DISimple/DIComplex/etc.
> and make that trait available in the japi/sapi so that
> InfosetIOutputters can use it. Passing in DISimple/DIComplex/etc.
> directly to the InfosetOutputters may have been a mistake, but since
> there's really no Java/Scaladoc available for it I don't think we need
> to worry about breaking backwards compatibility since no one could
> really use this API as is. I suspect this new trait would essentially
> have one public method for each of the members in the DFDL Infoset [1]?
>
> - Steve
>
> [1] https://daffodil.apache.org/docs/dfdl/#_Toc398030646
>
> On 02/22/2018 12:30 PM, Mike Beckerle wrote:
>> I was looking at our javadoc and scaladoc for rc2, as linked from here:
>>
>>
>> https://daffodil.apache.org/releases/2.1.0/
>>
>>
>> My mental experiment was to write my own Java InfosetOutputter (something requested by folks at AFRL) to directly output RDF triples from a parse.
>>
>>
>> This turns out to be impossible, as our scaladoc for InfosetOutputter, does not allow one to drill into the DISimple, DIComplex or DIArray classes/traits of the arguments to the InfosetOutputter method calls.
>>
>> Do we provide the general scaladoc tree for all of daffodil anywhere online other than in a javadoc archive that can be pulled as a managed dependency?
>>
>>
>>
>>
>>
>
>
Daffodil-1909 (JAPI/SAPI thing)
Posted by Mike Beckerle <mb...@tresys.com>.
Steve,
At one time there was a issue with the JAPI/SAPI design.... redundant stuff there, awkward to add things, etc.
In glancing at it the other day it looked unfamiliar to me. Was this fixed, or is that still outstanding work we need to do? If so we should add comment to Daffodil-1909 to that effect, or link it to other JIRA tickets about that issue.
...mikeb
________________________________
From: Steve Lawrence <sl...@apache.org>
Sent: Thursday, February 22, 2018 1:22:00 PM
To: dev@daffodil.apache.org; Mike Beckerle
Subject: Re: more scaladoc needed?
We do not currently provide the general scaladoc tree for all of
daffodil online anywhere. And I'm hesitant to provide that since I view
anything not in the daffodil-japi or daffodil-sapi subprojects as
internal and subject to change (i.e. not suitable for an API).
I think DAFFODIL-1909 that you just added is the right approach to solve
this. We should add an abstract class/trait that provides a minimal and
maintainable interface to the internals of the DISimple/DIComplex/etc.
and make that trait available in the japi/sapi so that
InfosetIOutputters can use it. Passing in DISimple/DIComplex/etc.
directly to the InfosetOutputters may have been a mistake, but since
there's really no Java/Scaladoc available for it I don't think we need
to worry about breaking backwards compatibility since no one could
really use this API as is. I suspect this new trait would essentially
have one public method for each of the members in the DFDL Infoset [1]?
- Steve
[1] https://daffodil.apache.org/docs/dfdl/#_Toc398030646
On 02/22/2018 12:30 PM, Mike Beckerle wrote:
> I was looking at our javadoc and scaladoc for rc2, as linked from here:
>
>
> https://daffodil.apache.org/releases/2.1.0/
>
>
> My mental experiment was to write my own Java InfosetOutputter (something requested by folks at AFRL) to directly output RDF triples from a parse.
>
>
> This turns out to be impossible, as our scaladoc for InfosetOutputter, does not allow one to drill into the DISimple, DIComplex or DIArray classes/traits of the arguments to the InfosetOutputter method calls.
>
> Do we provide the general scaladoc tree for all of daffodil anywhere online other than in a javadoc archive that can be pulled as a managed dependency?
>
>
>
>
>
Re: more scaladoc needed?
Posted by Steve Lawrence <sl...@apache.org>.
We do not currently provide the general scaladoc tree for all of
daffodil online anywhere. And I'm hesitant to provide that since I view
anything not in the daffodil-japi or daffodil-sapi subprojects as
internal and subject to change (i.e. not suitable for an API).
I think DAFFODIL-1909 that you just added is the right approach to solve
this. We should add an abstract class/trait that provides a minimal and
maintainable interface to the internals of the DISimple/DIComplex/etc.
and make that trait available in the japi/sapi so that
InfosetIOutputters can use it. Passing in DISimple/DIComplex/etc.
directly to the InfosetOutputters may have been a mistake, but since
there's really no Java/Scaladoc available for it I don't think we need
to worry about breaking backwards compatibility since no one could
really use this API as is. I suspect this new trait would essentially
have one public method for each of the members in the DFDL Infoset [1]?
- Steve
[1] https://daffodil.apache.org/docs/dfdl/#_Toc398030646
On 02/22/2018 12:30 PM, Mike Beckerle wrote:
> I was looking at our javadoc and scaladoc for rc2, as linked from here:
>
>
> https://daffodil.apache.org/releases/2.1.0/
>
>
> My mental experiment was to write my own Java InfosetOutputter (something requested by folks at AFRL) to directly output RDF triples from a parse.
>
>
> This turns out to be impossible, as our scaladoc for InfosetOutputter, does not allow one to drill into the DISimple, DIComplex or DIArray classes/traits of the arguments to the InfosetOutputter method calls.
>
> Do we provide the general scaladoc tree for all of daffodil anywhere online other than in a javadoc archive that can be pulled as a managed dependency?
>
>
>
>
>