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
1 Like
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.

8

How did you do that?

Can you use the new version with Alire? And if so: how?

9

Gnatdoc is extensible via Python. You can find the code that worked at this link. You’ll want to look at the usage here.

I had plumb forgotten about this, so I’m not sure I can provide more guidance than that.

1 Like
10

I suppose new GNATdoc is available in Alire.

11

I wasn’t able to make gnatdoc work with only Alire. Currently I use alr exec -P1 -- gnatpp with gnatpp coming from GNATStudio.app which @simonjwright provided.

This is of course a kludge. Hence my question.

12

The above isn’t a valid formal parameter specification; though it would be with (<>).

1 Like
13

Not me, that was Blady at Sourceforge

1 Like