.NET "langword" doesn't work

[eli-darkly]

A previous issue #185 reported that XML comment tags in the form <see langword="null"/> were being completely stripped. What I'm seeing now (with DocFX 2.57.2) is a bit different: they are transformed into plain text in the form langword_csharp_null, langword_csharp_int, etc. A Google search for such terms will show various projects that presumably generated their docs with DocFX (example).

I noticed this file in DocFX's own documentation build, which makes me think that this is a known behavior and that projects are expected to provide their own mappings like this, but I can't think why that would be, and the behavior doesn't seem to be documented.

[WalkerCodeRanger]

With DocFX 2.59.0, the behavior now seems to be that keywords in the langwordMapping.yml file are converted to spans with the xref style, but keywords missing from the langword mapping still show up in bad plaintext form. For example, <see langword="struct"/> in C# shows up as langword_csharp_struct in a span with the xref style on it.

If a langword is not supported, it should probably show up in the output as itself either as simply code or as an xref. Possibly, metadata generation should generate warnings for unsupported langwords.

[ison]

I know this is old but, in case others run into this problem, solution actually is documented here.

Per documentation:

langwordMapping.yml lists supported language keywords in DocFX. DocFX leverages cross reference to reference language keywords. You can disable default langword resolver and apply your customized one by calling docfx build --xref yourLangword.yml --noLangKeyword

If you're using docfx.json you can set the noLangKeyword property under build to true and add a link to your custom langword yml to xref property under build. This should solve the problem.

[eli-darkly]

@ison I'm still unclear on whether the langwordMapping.yml file you linked to there (which I believe is the same one I mentioned in my original post) is actually used by DocFX by default when building my projects. Based on its location under Documentation/, it looks to me more like it is part of the build for DocFX's own documentation. That would be contrary to what the docs are saying, but it would fit with the behavior I observed which was that it would not resolve such keywords unless the project being built explicitly provided its own mappings.

[eli-darkly]

And, if the behavior I described still exists, where all unrecognized keywords are converted into plain text with a langword_csharp_ prefix added, I would still call that a bug. @WalkerCodeRanger's comment 7 months ago said that that behavior did still exist, and I haven't checked lately, but nothing in your latest comment or the docs you linked to indicates that the behavior was fixed. I think it's fair to say that virtually everyone would expect the behavior for any kind of decorator of a symbol, if the symbol is unrecognized, to be that the symbol appears as it did in the original text and that you simply don't get whatever linking/styling behavior the decorator was supposed to provide— not that a prefix like langword_csharp_ would be inserted into the text.

[ison]

@ison I'm still unclear on whether the langwordMapping.yml file you linked to there (which I believe is the same one I mentioned in my original post) is actually used by DocFX by default when building my projects. Based on its location under Documentation/, it looks to me more like it is part of the build for DocFX's own documentation. That would be contrary to what the docs are saying, but it would fit with the behavior I observed which was that it would not resolve such keywords unless the project being built explicitly provided its own mappings.

Hmm. So you're saying you cannot get DocFX to resolve any langwords? That is indeed odd and is not the behavior I'm observing. Did you set noLangKeyword to tue by chance and did not supply a custom mapping? Using the default resolver, I am able to produce correct words for supported langwords (e.g., true) but will produce the uid pattern as you've indicated for words that aren't supported (e.g., this or catch). I was able to resolve this by creating custom langwordMapping.yml file that includes language key words that I needed. As per comment on whether to consider this a bug, I suppose one can consider it bug, though one that can easily be circumvented (at least in my experience).

[paulushub]

And, if the behavior I described still exist...

Just tested it, and it works with the embedded/default langwordMapping.yml, except that the absence of a language filter (C#, VB.NET, F# etc) limits its value.

You can verify and close the issue.

[eli-darkly]

@ison:

As per comment on whether to consider this a bug, I suppose one can consider it bug, though one that can easily be circumvented (at least in my experience).

I mean... if for instance the behavior of <see cref="X"/> when it didn't know how to resolve a link for X was that it would put some text like unknown_cref_X into the output, rather than either just putting an unstyled X into the output or signaling an error, and such behavior was both undocumented and not something anyone would want, I think most people would consider that a bug. It could be circumvented by making sure that you never had any unknown link targets, sure; that doesn't mean it's not worth fixing.

@paulushub:

Just tested it, and it works with the embedded/default langwordMapping.yml

To be clear, are you only saying that it correctly handles known C# keywords like null... or that it no longer has the behavior @WalkerCodeRanger described in the follow-up comment, where a keyword that's not found in the mappings turns into langword_csharp_*?

I'm still going to test it myself too - just wondering which kind of test you did.

[paulushub]

I'm still going to test it myself too - just wondering which kind of test you did.

I was referencing your post, and the post you referenced. By my tests, all known langword are transformed into <span class="xref">langword</span>.

As on @WalkerCodeRanger post of missing/undefined langword, that is similar to all see support currently. If not found, the comment is removed.