Gnatdoc and generic package parameters

General
1

gnatdoc doesn’t seem to document generic parameters to a package. Does that sound right?

In case my meaning isn’t clear, the following specification should do the trick. Ask away if not.

-- @summary this commentary appears (as long as there's no space between it and "generic" keyword)
generic
   type T is <>;
   -- commentary on T does not appear
   function "=" ( Left, Right: T ) return Boolean is <>;
   -- commentary on "=" does not appear
package P is
   -- commentary in here appears
2

For kicks, try spacing it out more:

-- @summary this commentary appears (as long as there's no space between it and "generic" keyword)
generic 

   type T is <>;
   -- commentary on T does not appear

   function "=" ( Left, Right: T ) return Boolean is <>;
   -- commentary on "=" does not appear

package P is
   -- commentary in here appears

I don’t use gnatdoc anymore, but in the distant past having everything clumped together got it confused (I’m hoping that is no longer an issue these days).

1 Like
3

The formatting is artificial to the original post. In my file, I ran the GNAT Studio code editor formatter. The spacing is there. Your suggestion is how I format my files normally, anyway.

I eventually got something sort-of acceptable by adding a custom @generics tag and placing that along with the documentation of the generic parameters in the package description, but that leaves a lot to be desired. My incompetence at creating a custom tag isn’t helping.

4

My apologies then. I was not trying to be artificial.

5

I think you misunderstood. I meant that my original post’s example was aritificial, and so the formatting was likewise artificial. I usually format things the same way you did.

6

You code snippet is not valid Ada code, thus GNATdoc can’t process it.

Also note, there are two versions of GNATdoc. Old one has known limitations on processing many constructs. New one is based on LAL, it is able to process almost all constructs, however it doesn’t support all features of old version on GNATdoc (like @summary tag). New version is used by ALS to create descriptions of the entities in tooltips.

If you observe any issues with entities description created by recent version of ALS, you can create ticket on GitHub.

7

Sorry, what’s invalid? Keep in mind that it was an example, an excerpt off the top of my head, to illustrate the basic idea. It wasn’t meant to be fully fleshed-out code.

If you want to see the code I was actually struggling to get gnatdoc to document, you can find it here.