I haven't found a good place for some documentation of CasIOUtils yet. I assume the correct book would be: https://uima.apache.org/d/uimaj-current/references.html
We could add it to Section 7 or Section 8, but both are not really suitable. There is probably not enough to say for a new section. We could restructure the sections, add a general section about serialization formats and there a subsection about how to use CasIOUtils. This could maybe delay the relase I also looked for the documentation of CasCreationUtils, but found none. Maybe the Javadocs are enough? Best, Peter Am 19.07.2016 um 08:49 schrieb Peter Klügl: > Hi, > > > yes, the class should be officially available to external code. I > already included it in the CAS Editor and in Ruta. I also plan to use it > in our inhouse code. I'll change the enforcer rule. > > > I can write the docs but any help is welcome since I do not know how > much spare time I have for the rest of the week for this. I'll take a > look where the documentation should be added. Haven't looked to it for > some time ;-) > > > I just chose the name of the class Richard contributed since I thought > it is really suitable. Then, I also noticed the uimaFIT class. This is a > not really good situation, but I would not change the name because of it. > > > I would not split the API form the implementation. I do not see any > advantages right now. The class is just a simple utils class with only > static methods like CasCreationUtils (which is also not separated). > > > Best, > > Peter > > Am 18.07.2016 um 22:26 schrieb Marshall Schor: >> This is OK with me. I can even volunteer to write the docs (but am happy to >> others do it :-) ). >> >> I'll wait to hear about the split (if any) between the public API and the >> impl. >> >> And, we'll need to change the next version # to 2.9.0, from 2.8.2, due to >> this >> being that kind of a change. >> >> Is everyone OK with all of this? >> >> -Marshall >> >> On 7/18/2016 2:39 PM, Richard Eckart de Castilho wrote: >>> I believe the intention is that this class becomes part of the public API. >>> >>> Also, my understanding is that it would do a superset of what the >>> uimaFIT class by the same name does. We could then probably deprecate >>> the respective uimaFIT class and suggest using the core class instead. >>> >>> Best, >>> >>> -- Richard >>> >>>> On 18.07.2016, at 20:30, Marshall Schor <[email protected]> wrote: >>>> >>>> This is a new class added to uimaj-core project, in org.apache.uima.util >>>> package. This is fine if this is to be part of the official public APIs >>>> supported by UIMA going forward; but if that is the case, it should >>>> probably be >>>> documented in the UIMA docs, and we'd have to change the version number >>>> (due to >>>> enforcer rules). >>>> >>>> If this is more of an internal use utilities, then it should be in one of >>>> the >>>> internal use packages, such as >>>> >>>> org.apache.uima.internal.util >>>> >>>> This class is similarly named to a UIMAFit class; are these related? >>>> >>>> If some of the APIs are to be permanent and public and part of the official >>>> public APIs, but some are internal implementation details, please consider >>>> using >>>> an interface and an ".impl" (or equivalent) approach; packages which >>>> support >>>> these are: >>>> >>>> org.apache.uima.util and >>>> >>>> org.apache.uima.util.impl >>>> >>>> -------------- >>>> >>>> If this is only an internal kind of change, not intending to affect the >>>> official >>>> UIMA APIs, then moving to the internal.util package will fix the "enforcer" >>>> error the build is currently getting. >>>> >>>> -Marshall >>>>
