Can we stop trying to document the file format? Is it really needed? It has been an error-proned process over time...
Can't the source code be the definitive resource one reads to determine how a codec stores stuff....? Mike McCandless http://blog.mikemccandless.com On Tue, Oct 4, 2011 at 3:17 AM, Andrzej Bialecki <[email protected]> wrote: > On 04/10/2011 08:16, Simon Willnauer wrote: >> >> hey folks, >> >> with lucene 4 we got tons of new file formats which are different from >> what we have in our fire format specification. This is going to be >> worse once we add more codecs like PFOR etc. However updating the docs >> manually is going to be very error prone so I wonder if somebody has >> any idea how we can automate this or maybe generate this from the >> sources somehow. Any ideas? > > At least the list of file names that a codec uses can be generated easily... > perhaps we could turn these names into enums and add annotations about their > function? I added this manually in Luke some time ago, and that mapping from > name to function is already getting stale. > > Still, detailed docs about per-file formats are needed, and I don't see > other way than the venerable javadoc, and a discipline to fill in the > javadocs for all codecs. Perhaps we could use separate html files with docs > per file and tie them somehow via annotations so that they can be processed > by a doclet. > > -- > Best regards, > Andrzej Bialecki <>< > ___. ___ ___ ___ _ _ __________________________________ > [__ || __|__/|__||\/| Information Retrieval, Semantic Web > ___|||__|| \| || | Embedded Unix, System Integration > http://www.sigram.com Contact: info at sigram dot com > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
