I don't think any decisions have been made explicitly about what formats to write documentation in, if that's what you mean. Quite simply, we just have not written any documentation. We're an overworked project with a long list of technical goals, fast-moving development, and just a few hackers working on it without much in the way of organization. Writing documentation just has not risen near the top of the pile.
Were you thinking primarily about documentation for the various command-line tools, or for the library APIs, or both? We are fairly fastidious about putting details in --help output for the tools. Many "eu-foo" tools are replacements for an existing "foo" tool implemented in binutils. Those interfaces are well-known, the binutils tools are documented and people are familiar with the syntax from those, and we strive for command-line compatibility for common uses (and most of the non-arcane uses, really) of these tools. Various of those (e.g. eu-addr2line, eu-strip) have nifty feature options that their binutils counterparts never had, but at least --help is fairly informative about those. The library APIs fall into two categories. Most of the libelf API has been quite stable for many years and is consistent with other implementations that have lots of documentation (e.g. Solaris). The corners of libelf that are new or specific to elfutils are few and arcane, perhaps only used by elfutils tools' themselves. So while this API is pretty solid and could be documented thoroughly without much risk of drift, the lack of such documentation has probably not been a practical hindrance to people trying to write to the API. The other libraries (libdw/libdwfl, etc.) have been much more fluid and continue to change pretty rapidly. We expect these to keep changing and expanding for some time. By the end of this year, we will probably have even more of these, APIs in more languages, etc. The horizon when these APIs become stable is pretty hazy at this point. (By the same token, we are and will be adding more new command-line tools whose usage details will keep evolving too.) A major goal in having all these new APIs come together is to get more people writing things using them, and to have a low barrier to entry in casually whipping up new things. Clearly, good library API documentation is essential for that ever to take off. We make some effort in writing detailed comments in API header files along the way, as is necessary just for our own use. The detail is better in some places than others, but in all places it's really just concise (terse) pointers for hackers who are prepared to read a lot of C rather than a formal API document of any kind. So, in summary, we would love to have great documentation but have almost no cycles to devote to it any time soon ourselves (just being realistic). For some basic stuff like libelf and the existing command-line tools, it is just a question of getting it written. For the cool APIs and the even cooler vaporware believed or imagined to be in the pipeline, it will be a major and ongoing effort to produce documentation that is sufficiently accurate and detailed to be really useful, and to keep it so. We haven't made any real plans for either. Assistance is welcome. Thanks, Roland _______________________________________________ elfutils-devel mailing list [email protected] https://fedorahosted.org/mailman/listinfo/elfutils-devel
