Add ability to interpolate field names in the doc-strings

[Mingun]

Because doc attribute translates to native language doc-strings, sometimes you want to refer in it to some field of some type. But, because different languages has different rules for identifiers, you can't write documentation, that will be appropriate for all languages. In addition, it is desirable to specify cross-references for those languages that allow it. For example, in Javadoc you want to insert {@link something} tags.

So it will be great, if you can write documentation with some placeholders, that will be replaced to formatted content. This should handle both built-in type attributes, such as size on arrays, and custom. For example:

doc: Pascal string
seq:
  - id: len
    type: u1
  - id: content
    doc: Use [[content.size]] to get string length
    type: u1
    repeat: expr
    repeat-expr: len

javadoc for content method must be rendered into:

/** Use {@code content().length} to get string length */

Notice, how content.size converted into {@code content().length}. _.size can be converted into {@code length}

[GreyCat]

Makes pretty good sense, actually. I'm not sure about `[[...]]`` syntax, as we were aiming for Markdown / CommonMark compatibility, but embedding expressions / type names, translating it to the target language notation is a very good idea.

[KOLANICH]

doc: Use [[content.size]] to get string length

when applied to a content field is an example of completely useless pointless junk.

Usually we

• don't want to refer an own field - doc is all about describing own field;
• we don't want to refer special props because they are part of language with known semantics;
• we refer other fields, but not as code - relationships that make sense as code should be expressed in KS, not in comments; We usually describe semantic relationships that cannot be expressed as code at all this way.

[Mingun]

when applied to a content field is an example of completely useless pointless junk.

Yes, it just an example, perhaps not as good as it can be. Yet another example. I have structure in the protocol:

Size	Description
	Delimiter
1	Denomination code, assigned to cassette. Repeated for number of cassettes in the ATM
	Delimiter
5	Count of notes in each cassette. Repeated for number of cassettes in the ATM, the same count, as previous field
...	other fields

Right now I model this, as

seq:
  - contents: [0x1E]
  - id: denominations
    doc: Because kaitai-struct limitations last array element is not used and not an actual value, but delimiter instead
    type: u1
    repeat: until
    repeat-until: _ == 0x1E
  - id: counters
    doc: Count of notes in each cassette. Has the same size, as [[denominations]]
    type: int(5)
    repeat: expr
    repeat-expr: denominations.size - 1

I want to write in counters documentation that it has the same count of elements, as denominations and leave link to that field. This relationship not expressed in types for user of generated class

[KOLANICH]

Has the same size, as [[denominations]]

Unneeded, since you have repeat-expr: denominations.size - 1