[stringtemplate-interest] Javadoc generation using ST ?

[Zenaan Harkness]

On Sat, Apr 19, 2008 at 09:19:53AM +1000, Zenaan Harkness wrote:
> Everything seems as though it should work. Yes, I'm missing this:
> 
> My apologies. From the ST3.1 docs:
> 
> "... StringTemplate should wrap lines in between expression elements.
> StringTemplate never breaks literals, but it can break in between a
> literal and an expression."
> 
> I have been sending in single strings, for my javadoc section, thinking
> the string (single element from the template's perspective) would get
> broken up for wrapping purposes. Clearly I didn't read the docs
> properly on first glance.
> 
> Now I just have to jig my model to do the required wrapping and bundling
> into lists of Strings. Which should be relatively easy.

OK, my strings originally had \n embedded in them to separate lines
(created with vim in unix environment).

So I tried to split the string, ended up achieving this with
s.split("\n").

Now, some of my Javadocs, especially my class-level javadocs, are
multiple paragraphs.

As you can see even in this email, most paragraphs end with a line
shorter than the average line length of that paragraph. Which means,
from ST perspective, that the next line needs to be joined to that line
(and so on), until the right length of line is achieved (which is
longer than what I want). This also has the ugly habit of consuming
blank lines, which for those versed in javadoc, means no separate
paragraphs - all becomes one.

What to do again.

I realise I could break up the text into paras, and pass in a list of
paras to ST, and each para is a list of strings, for each line of the
paragraph. This is just more code in my model, new para-storing beans
etc, than I am prepared to fiddle with just for line formatting. This
would be imposing significantly on my model - my data representation,
simply to suit the template processing engine.

I contemplated hacking an AutoIndentWriter subclass, and passing that in
to the specific templates in my template groups (I have quite a
hierarchy of ST groups building up), but again it seems like just too
much work, having to locate specific templates by name, etc - the
model's controller (or the model itself) has to have some knowledge of
the specific template names, in order to apply the new writer at just
the right spot in the template hierarchy.

Which leads me to the thought of the ideal:

Ideally, I'd like ST to have a wrap_at_regex="\N" option to go with the
wrap=" * " option, where the \N means wrap at every newline in the
string.

You see, in my model data, it's simply layed out in plain text files,
loaded/ deserialized into my Java bean/model objects, and then passed
into the appropriate top level StringTemplate for view generation. A
template attribute or two would be the most pain free way to get what I
desire.

While we're at it, we might as well have a wrap_at_length=# option :)

What to do.

It dawned on me that the functionality of AutoIndentWriter is already
doing almost what we want - it's inserting the appropriate prefix for
each line - which is not just spaces, but a combination of spaces and/
or tabs, as per the input at each higher-level template, AND, this even
works when newlines are embedded in a string to be spat out (eg. a
javadoc comment) - ie the spaces and/or tabs prefixing the line at that
point are output at the beginning of each line _of the string so spat_.

So it's probably an easy jig to build this functionality into
AutoIndentWriter.

For me, I have hacked my model, to split all my javadoc strings at \n,
then to join them again with the exact string " * " prefixing each line
but the first.

VOILA! Javadoc output is being produced with precision, with only simple
newlines embedded into the source data text files as required/ desired.

Well, it's been a marathon of recursive frustration today, but I
achieved the result I need.

Hope the info's useful for someone,
Zen

-- 
Homepage: www.SoulSound.net -- Free Australia: www.UPMART.org
Please respect the confidentiality of this email as sensibly warranted.