javadoc and XML docs render authored Markdown literally: the Formula block welds prose, and emphasis ships as asterisks

[mario4tier]

The canonical input/<name>/<name>.md is Markdown. Rust's target is Markdown too, so rustdoc renders it. Java's target is HTML and C#'s is XML, and their emitters convert only part of it — so the rest ships to users as literal punctuation, in the published javadoc, the NuGet XML docs, and every IDE hover.

Two independent causes, both measured on dev at e63a7218b.

1. ## Formula welds its trailing prose into the code block

parser::doc_md::split_formula_note separates the formula from the sentence after it only when the section carries a closing $$. Across the corpus, 2 of 150 ## Formula sections do. For the other 148 the whole section — formula and every prose paragraph under it — is handed to the emitters as preformatted text.

62 lines land inside <pre>{@code} in Core.java, and 62 inside <code> in the C# sources, across 22 indicators: ADR ADX APO ATR CMOU COPPOCK CUMSUM DPO EFI EMA ER ERI FRACTAL MIDPRICE PPO PVO QSTICK RVI VHF VORTEX VWMA WAD.

Core.java, COPPOCK:

* <p><b>Formula</b>
* <pre>{@code
* `COPPOCK = WMA(ROC(optInROC1Period) + ROC(optInROC2Period), optInWMAPeriod)`
* Each ROC carries [`ROC`](/functions/roc)'s own zero guard — a zero price `optInROC*Period` bars back yields 0.0 …
* The formula is symmetric in the two ROC periods and the lookback keys off their max, so `optInROC1Period > …
* The classic defaults are 11/14/10 on monthly data. Wikipedia's daily-scale variant (231/294-bar ROC, 210-bar …
* }</pre>

Three prose paragraphs as code, the formula keeping its literal backticks, and a Markdown link as text. The same source renders correctly on ta-lib.org (website/src/functions/coppock.md), which is what says the .md is right and the emitters are wrong.

This is also why 6 Markdown links survived the conversion added in #386 (e46e97c0a): they sit inside the formula block, which never reaches jdoc/csdoc. COPPOCK, ERI and VORTEX, x2 overloads.

2. Markdown emphasis ships literally into ordinary prose

jdoc and csdoc convert backtick spans and (since e46e97c0a) inline links. They do not convert **bold** or *italic*, so those reach the reader as asterisks — this time outside any code block, in summaries and notes.

	**bold**	*italic*
Java Core.java	16	39
C# Core_*.cs	16	38

e.g. weighted moving average of the **sum** of two rates of change and how far price travels *within* a bar.

Rust's counts are non-zero too and are correct — rustdoc renders Markdown. Only the HTML and XML targets need the conversion.

Nothing catches either

Measured, not assumed: javadoc -Xdoclint:all,-missing (the setting pom.xml enforces) and csc under TreatWarningsAsErrors + GenerateDocumentationFile both accept literal Markdown without a diagnostic. regen-check only pins that the committed output matches the emitter, so it agrees with whatever is emitted. This is the same blind spot #386 hit with links, where Rust was clean only because rustdoc's bare_urls lint made a stranded URL a build failure.

What a fix has to decide

• split_formula_note needs a second delimiter form — a formula line followed by a blank line and prose. That changes what 148 functions render as a formula in four backends, so it wants its own before/after diff review rather than being folded into a doc-emitter change.
• Emphasis conversion is local to jdoc/csdoc (<b>/<i>), and is the smaller half. It can land independently.
• Rust must not change: it already receives Markdown and wants it.

Guard the result with a unit test on the escapers plus a corpus assertion that no rendered Java/C# doc line carries **, ](, or a stray backtick outside a code block — nothing else can see this class.

[kevinlincg]

The emphasis half is in (#407). Before starting the ## Formula half I surveyed
what the corpus actually contains, and it does not match the shape the deliverable
assumes — so posting the survey rather than a PR built on the stated rule.

Measured on 433a519b9, all 150 ## Formula sections.

The stated rule reaches 15 of the 22

split_formula_note needs a second delimiter form — a formula line followed by
a blank line and prose.

That shape is real and is the majority: 15 of the 22 are exactly it (adr
apo coppock cumsum efi er eri midprice ppo pvo qstick vhf
vortex vwma, plus fractal if its lead-in is treated as formula). The other
seven are two shapes a blank-line delimiter cannot reach.

Four have the prose first

dpo fractal rvi wad open with a lead-in and put the formula after the
blank line:

Let `t = optInTimePeriod / 2 + 1`, an integer division, so a period and its
odd successor share the same displacement.

    DPO[i] = P[i - t] - SMA(P, optInTimePeriod)[i]

Implemented the direct way — split at the first blank line, prose is what
follows — this inverts all four. Run against the corpus:

	rendered as the formula	rendered as prose
dpo	Let \t = optInTimePeriod / 2 + 1`, an integer division, so …`	DPO[i] = P[i - t] - SMA(P, optInTimePeriod)[i]
fractal	With \L = optInLeftBars`, … and pivot `c = i - R`:`	swingHigh(i) = 100 if … swingLow(i) = 100 if …
rvi	With \S` the standard deviation of …, and `C` the input series:`	U[i] = … D[i] = … RVI = 100 * RMA(…)
wad	For each bar t:	TRH_t = … TRL_t = … WAD_t = WAD_{t-1} + AD_t

rvi and wad are worse than a swap: the note is joined into a single line (it
has to be — every emitter prefixes each line it is handed), so three and seven
formula lines respectively collapse into one run-on.

A guarded implementation — "only split when the first block is a formula" —
does not invert, but then it leaves these four exactly as they are today, and
"is this block a formula" is the part that needs deciding. Indentation does not
answer it: dpo rvi wad indent their formulas, fractal does not.

Four have no blank line at all

adx atr cmou ema are a single block, so there is no delimiter to key on.
The prose is welded into the same line:

k = 2 / (period + 1); EMA_t = (price_t - EMA_{t-1}) * k + EMA_{t-1}. Seed: EMA = SMA of first `period` bars.

Splitting that is a judgement about where the formula ends, not a delimiter.
atr is the same in three lines, one of which reads both ways:
ATR seed = simple average of first \period` TR values`.

What this changes about the plan

The blank-line delimiter is worth having — it is 15 of 22 and it is unambiguous
where it applies. But it wants the guard, or it silently inverts four functions
in four backends each; and it closes 15 of the 22, not all of them, so the issue
should not close on it.

The remaining seven need a formula/prose call per function, which is authorial. I
have not made it. If you want the split delimiter with the guard as its own PR I
can do that half and record the seven; I did not want to guess the wording of a
## Formula block on 148 functions' behalf.

For the record, the shape counts across all 150 sections: 2 carry $$ (already
handled), 113 are a single block with no trailing prose at all (nothing to
split), and 35 are multi-block — of which the 22 here are the ones whose later
or earlier blocks are prose.

[mario4tier]

Part 2 (Markdown emphasis) is fixed by #407 — thanks @kevinlincg. Measured on dev at 350b01274: 1,450 <b>/<i> tags in Core.java and 0 literal ** left in javadoc prose.

Part 1 — ## Formula welding its trailing prose into the code block — is still open, and a review of the #386 landing turned up a third defect in the same family, worth folding in here:

Eight Java stream classes claim peek never allocates while allocating. java_stream.rs's allocates predicate is syntactic on the handle's own frame body (a .clone() or a = new …Out(); line), so it never looks through a sub-handle call. MaStream.peek allocates a MamaOut when optInMAType == MAType.MAMA, and eight handles drive MaStream sub-handles — ApoStream, BbandsStream, MacdextStream, MavpStream, PpoStream, PvoStream, StochStream, StochfStream. All eight are emitted with "It copies nothing: … and peek never allocates."

Measured on the built jar (getThreadAllocatedBytes, 300k warmed iterations, stock JVM): BBANDS peek 32.0 B/call, APO 64.0, MACDEXT 96.0 — exactly 32 B per MA sub-handle — against 0.000 B for the same functions at MAType.SMA.

The awkward part is that no static per-function sentence is correct: the cost is conditional on a runtime parameter. So this needs a decision about what the javadoc should say, not just a predicate fix — which is why it is here rather than patched in passing.

https://claude.ai/code/session_01Vbo6rRkQaiKvTLcturhzxw

[kevinlincg]

On the third defect — I did not touch the wording, since you've reserved that
call. Six facts about its scope, all read off dev at 8d67ba078, because the
set and the backend it applies to both turned out to be narrower than they look.

1. The set is exactly your eight; there is no ninth. Transitive closure over
all 201 stream classes: three direct peek allocators (KdjStream
MaStream StochrsiStream) and eight reached only through a sub-handle
(ApoStream BbandsStream MacdextStream MavpStream PpoStream PvoStream
StochStream StochfStream).

2. Getting there needs three call shapes, and keying on one silently misses the
rest. The emitted sub-handle invocation has three forms:

((MamaStream) sp.sub).peek(inReal)     // cast — MaStream's own switch
sp.sub0.peek(inReal)                   // plain field — APO, PPO, BBANDS, …
sp.bank[slot].peek(inReal)             // array element — MAVP only

My first pass matched only the cast form and reported zero transitive
allocators. My second added the plain field and reported seven — it dropped
MavpStream, whose sub-handles are a MaStream[] bank. Both readings looked
like clean answers. Whatever replaces the predicate wants to be structural on
the frame rather than keyed on a call spelling, or it inherits the same failure
in a new place.

3. The predicate is wrong in one direction only. No handle carries the
allocating sentence while not allocating — the reverse sweep is empty. And the
three direct allocators are detected correctly today, so nothing about the
syntactic test on the frame's own body is broken; the whole defect is that it
stops at the frame boundary.

4. Only …Out() allocates on the success path. Every new inside any of the
201 peek bodies: new StochOut / new MamaOut / new StochfOut (the three
above), and new TaLibArgumentException — which is the rejection path, in all
201, and is not what the sentence is about. So the sentence has no other
counterexample hiding in it.

5. C# is not affected, and not because its predicate is better. csharp_stream.rs
keys on Array.Copy( in the frame, which is about copying accumulators, not
allocating — and it never fires: 201 of 201 C# stream classes get the
never-allocates sentence, 0 get the other one. It is nonetheless correct,
because the two backends carry a multi-output sub-result differently:

MamaOut subValue = new MamaOut();                              // Java: heap

MamaValue subValue = ((MamaStream) sp.sub!).Peek(inReal);      // C#: by value

MamaValue is public readonly record struct MamaValue( double MAMA, double FAMA )
(Core_MAMA.cs:1021), so the C# path has no per-call heap allocation to
document. The same source construct allocates in one backend and not the other,
which means the wording decision is Java-only — the usual cross-backend
consistency rule does not pull C# in here.

Not measured, read statically: I have no .NET SDK that can target this project,
so the C# half of #5 is a read of the emitted code and the record-struct
declaration, not an allocation measurement like yours. If the decision ends up
resting on it, it wants the same getThreadAllocatedBytes-style check on the
.NET side — a struct that escapes to a boxed context would change the answer, and
static reading cannot rule that out for every call site.

6. Rust and C never make the claim — the sentence exists only in
java_stream.rs and csharp_stream.rs.

[mario4tier]

The peek/update allocation claims are dropped, not corrected — 8ab6db8df.

Mario's call: whether a call allocates is an implementation detail that changes as the library is optimized, so publishing it buys a caller nothing and costs a doc that must be re-verified after every optimization. It was also already wrong, which is how it surfaced — the emitter decided by scanning the handle's own frame for a new <N>Out(), and that cannot see a sink allocated inside a sub-handle's step, so eight handles said peek "never allocates" while allocating 32–96 B/call under MAType.MAMA.

Gone from the generated Java and C# docs: peek's two-way "never allocates" / "allocates a small bounded amount" sentence, update's "Never allocates handle state", and value(out)'s "allocating nothing". The predicate that drove the split went with them. What stays is the contract a caller can plan against — the cost does not grow with the period — and, for the sink, what it is for rather than what it costs. Same reasoning applied to the public Java page and the design doc.

So this issue no longer has an allocation-doc item. With part 1 landed in 2e58acfe8 and part 2 in #407, everything raised here is now resolved.

https://claude.ai/code/session_01Vbo6rRkQaiKvTLcturhzxw

[mario4tier]

Both halves landed.

Emphasis — #407 (433a519b9). **bold** / *italic* become <b> / <i> in the javadoc and the XML doc, with doc_emphasis_suite sweeping every function's rendered blocks.

Formula — 2e58acfe8. Not by teaching split_formula_note a second delimiter form: the block is gone from the API doc targets entirely. Java and C# now carry the same Formula and more info at ta-lib.org/functions/<name> link rustdoc has had since f2fbf8b56, and ## Formula renders on the website only. That removes the preformatted block the surviving backticks and Markdown links lived inside — ]( in the generated Java and C# is now 0 — so the 148-of-150 split this issue asked for is moot. DocDef's two formula fields and split_formula_note went with it, and the javadoc-example gate no longer needs its GENCODE exclusion (that region held 233 formula code blocks; it holds none).

One thing the measurement turned up that was not in the original report: ## Notes is rendered by both targets and BBANDS ships $k_{\text{up}}$ there as literal source, invisible to -Xdoclint and to csc -warnaserror like everything else in this class. A notes bullet carrying TeX is now dropped from Java and C#, per bullet so its neighbours still ship. ## Summary and the per-argument prose are not droppable — they are the only definition a Java or C# user gets — so TeX authored there fails the build instead.