View Source

Annotated API

Because documentation often lags behind the actual development of libraries, if you are trying to understand StringTemplate you will likely need to read the javadocs documentation of the API, and probably delve into the source code itself. That's a reasonable idea, but the source code and javadocs currently have two issues that make that tough going.

Out-of-date: Some of the javadoc comments are particularly out-of-date, or are particularly narrow comments that misdirect away from more useful information.
Ambiguously-broad API: The various classes leave a large number of methods with public access (rather than protected), even though many of these methods are not intended to be part of the API for application programs to call. This blizzard of methods gets in the way of a reader being able to identify and focus on just the most-relevant ones (and invites convoluted misuse of the library).
- Public vs Package scope: There's a possible point of confusion when reading the javadocs (and the excerpt that I've annotated). In the summary tables, the declarations apparently omit the "public" access specifier (though these are shown in the detail listing of each field and method below the summaries). Consequently, methods and fields whose summaries lack an access specifier do not have package scope (as would be the case in actual Java source code) but instead probably have public scope.

So, the attached pages are my quick attempt to identify and highlight what I believe to be the relevant methods of the core classes, StringTemplate and StringTemplateGroup, and to add some commentary (helpful I hope) where the javadocs are, in my view, problematic.

It is my hope that these suggestions will be incorporated back into the actual source code, making this kind of page unnecessary.

These pages are based on copies of the actual javadocs, captured 2009-05-25 (version 3.2). Though I rearranged the order of the sections and methods to highlight the most relevant methods, I have not deleted any, so you still see the full view. (I have, however, skipped the lengthy bottom section that normally provides a separate section for every method and field, with extended blurbs for some. You can view that in the original javadocs if need be.)

Wiki note: These annotated API pages are written in html as the wiki markup language is too convoluted for this kind of document. This makes these pages somewhat unmaintainable. Hopefully some of this material can get incorporated back into the source code before too long.