XML comments on compounds appear twice

[PatrikLundell]

I tried to add a comment to a compound definition (df.world-data.xml:world_region_details.edges):

        <static-array count='16' name='seed' comment='looks random'>
            <static-array type-name='uint32_t' count='16'/>
        </static-array>

        <compound name='edges'
            comment='random comment'>

but when generated the world_region_details.h contents becomes:

    uint32_t seed[16][16]; /*!< looks random */
    /**                                                       <-----------------
     * random comment 
     */
    struct DFHACK_EXPORT T_edges {
          ***  The fields in the compound go here. Cut away for brevity.
      static struct_identity _identity;
    public:
      T_edges();
    };
    T_edges edges; /*!< random comment */<-----------------

The formatting also differs between the two instances if '&'#10; is used to create split line comments (Can't get the ampersand displayed correctly without the quotes). Also, the first definition (of 'seed') in the first quote isn't displayed, but just appears as blank lines, for some reason.

[lethosor]

Is 
 what you were trying to use? For multiline comments, using the <comment> tag is probably cleaner than embedding newlines in a single-line attribute.

Also, backticks (```) are what you need for code blocks, not quotes ('). https://guides.github.com/features/mastering-markdown/ has more. I fixed the formatting above to stop the `*`s from producing italic text.

Also, what's "the first definition (of 'seed')"? The definition you've pasted there should be all that's necessary. There's no "struct DFHACK_EXPORT" for it because it's a primitive type.

[PatrikLundell]

What I meant was that the first definition was that of 'seed', and that it was the one that wasn't shown (because of my failure to realize the ticks should be the backwards ones), not for any technical reason regarding the XML itself.

And yes, seems to achieve at least half of what I want without the uglification induced by forcing newlines. The half that's achieved is to get the comment into the generated .h file. However, I still get the comment duplicated when placed inside the compound:

        <compound name='edges'
            comment='In order to determine how biomes cross embark tile edges'>
            <comment>Trying
            a multiline
            comment</comment>
            <static-array count='16' name='split_x'
                          comment='splits for horizontal edges, x=min y=max'>
                <static-array type-name='coord2d' count='17'/>
            </static-array>

results in:

    /**
     * In order to determine how biomes cross embark tile edges
     * Trying
     * a multiline
     * comment
     */
    struct DFHACK_EXPORT T_edges {
      df::coord2d split_x[16][17]; /*!< splits for horizontal edges, x=min y=max */
      df::coord2d split_y[17][16]; /*!< splits for vertical edges, x=min y=max */
      int8_t biome_corner[16][16]; /*!< 0=Reference is NW, 1=Reference is N, 2=Reference is W, 3=Reference is current tile */
      int8_t biome_x[16][16]; /*!< 0=Reference is N, 1=Reference is current tile (adopted by S edge to the N) */
      int8_t biome_y[16][16]; /*!< 0=Reference is W, 1=Reference is current tile (Adopted by E edge to the W) */
      static struct_identity _identity;
    public:
      T_edges();
    };
    /**
     * Trying
     * a multiline
     * comment
     */
    T_edges edges; /*!< In order to determine how biomes cross embark tile edges */

(Don't mind the actual text: it's currently mostly placeholders to experiment with the commenting functionality).

The other thing I was trying to achieve was to get the comment picked up by Ragundo's dwarfexplorer tool, but it doesn't pick up the "comment" attribute on the compound anyway...

Edit: It seems the tag causes its contents to be placed before the item inside of which it's placed in the XML file, resulting in an annoying difference between the placement in the two files:

            <static-array count='16' name='split_x'
                          comment='splits for horizontal edges, x=min y=max'>
                <static-array type-name='coord2d' count='17'/>
            </static-array>
            <static-array count='17' name='split_y'
                          comment='splits for vertical edges, x=min y=max'>
                <static-array type-name='coord2d' count='16'/>
                <comment>another
                multi line
                comment</comment>
            </static-array>

results in:

      df::coord2d split_x[16][17]; /*!< splits for horizontal edges, x=min y=max */
      /**
       * another
       * multi line
       * comment
       */
      df::coord2d split_y[17][16]; /*!< splits for vertical edges, x=min y=max */

(and if placed outside of the static-array but in between the first and second one, it still gets pushed outside of the compound the two are part of, with the associated duplication).