Help Insight w/ XML Documentation not working

[Dan Barclay]

Ok, I've had a problem making XML Documentation do useful tricks for me but
I figured it was because I misunderstood what it was supposed to do. The
docs being what they are, I really haven't had a good grip on it.

However, seeing Pawel Glowacki's blog (Delphi XML Documentation Live
Template) it seems clear that if I put a <summary> tag on an element, the
text should show up in a tooltip when I over over a usage of the element.
It simply doesn't work for me.

Yes, I'm doing a full build on the project. Yup, I checked the unit.xml and
the <summary> text is there.

When I hover over a usage I get the Help Insight showing the definitinition
and parameter list, but no <summary> text.

I'll also report that there are two "links" showing on the tooltip and they
never go anywhere. I'm wondering if the two issues are related. The links
I'm referring to are, for example: Use EncodeDate(). Help insight says,
among other things "Declared in SysUtils". SysUtils is a link, but when I
click on the link I get:

Unable to locate: "ypelink:SysUtils"

So, what am I missing?

Thanks,
Dan

[Dan Barclay]

I forgot to mention: D2006, full install but in a Win32 project.

"Dan Barclay" <D...@MVPs.org> wrote in message
news:45c16e0f$1...@newsgroups.borland.com...

[Bill Mogk]

Dan Barclay wrote:
> Ok, I've had a problem making XML Documentation do useful tricks for me but
> I figured it was because I misunderstood what it was supposed to do. The
> docs being what they are, I really haven't had a good grip on it.
>
> However, seeing Pawel Glowacki's blog (Delphi XML Documentation Live
> Template) it seems clear that if I put a <summary> tag on an element, the
> text should show up in a tooltip when I over over a usage of the element.
> It simply doesn't work for me.
>
> Yes, I'm doing a full build on the project. Yup, I checked the unit.xml and
> the <summary> text is there.
>

<snip>

What got me, was the summary tag has to be in the interface section, not with
the implementation code. and, you don't have to rebuild the soucre for the
hint to show up - just type in the summary text, hover over the name and the
new text is in the tooltip.

Bill.

[Dan Barclay]

"Bill Mogk" <wm...@whmsoftware.com> wrote in message
news:45c1f449$1...@newsgroups.borland.com...

> Dan Barclay wrote:
>> Ok, I've had a problem making XML Documentation do useful tricks for me
>> but I figured it was because I misunderstood what it was supposed to do.
>> The docs being what they are, I really haven't had a good grip on it.
>>
>> However, seeing Pawel Glowacki's blog (Delphi XML Documentation Live
>> Template) it seems clear that if I put a <summary> tag on an element, the
>> text should show up in a tooltip when I over over a usage of the element.
>> It simply doesn't work for me.
>>
>> Yes, I'm doing a full build on the project. Yup, I checked the unit.xml
>> and the <summary> text is there.
>>
> <snip>
>
> What got me, was the summary tag has to be in the interface section, not
> with the implementation code.

AHHHGGG! I knew it would be simple. I've put it in the implementation
section (where it should be IMHO but that's irrelevant now). OK, so WHERE
is this info in the documentation? I'm sure it's in there somewhere but
I've looked and it's beyond my ability to find (could be me, could be the
docs, I'm not saying).

My bet is that there's something else in there I'd like to know about, so
I'd like to see it.

> and, you don't have to rebuild the soucre for the hint to show up - just
> type in the summary text, hover over the name and the new text is in the
> tooltip.

Cool. Thanks!

Dan

[Dan Barclay]

More problems with this:

It works on instances inside the unit in which it was declared. It DOES NOT
show the summary information when I use the function outside the unit. What
the heck?

I did a Project|Build, saved the files, unloaded the project, reloaded the
project, etc to see if any of that helped. No change.

What am I missing? Is there some setting or path that matters to this
critter? The source units are in "library/project" directories (that is,
project specific units are in one directory, common units are in another).

Dan

"Bill Mogk" <wm...@whmsoftware.com> wrote in message
news:45c1f449$1...@newsgroups.borland.com...

[jrodenhi]

Well. At least this is some progress, though. I can now see my comments
in the unit containing them. I have thought since I bought D2006 that I
really would value this feature if it worked.

I have one unit I call uCommon. I use it throughout my program because it
has a lot of useful procedures and functions that are not part of any
class. When I check out the uCommon.xml file, I see that the XML function
tag shows the visibility attribute as "private". I have tried editing the
file and changing it to "public" but it did not change the results.

Do user comments show up globally for anyone in Help Insight?

--- posted by geoForum on http://delphi.newswhat.com

[Bill Mogk]

Dan Barclay wrote:
> More problems with this:
>
> It works on instances inside the unit in which it was declared. It DOES NOT
> show the summary information when I use the function outside the unit. What
> the heck?
>
> I did a Project|Build, saved the files, unloaded the project, reloaded the
> project, etc to see if any of that helped. No change.
>
> What am I missing? Is there some setting or path that matters to this
> critter? The source units are in "library/project" directories (that is,
> project specific units are in one directory, common units are in another).
>
> Dan
>
>

{snip}

FWIW, I have/get the same probelms/results as you, in this case.

Bill

[Bill Mogk]

Dan Barclay wrote:
> "Bill Mogk" <wm...@whmsoftware.com> wrote in message
> news:45c1f449$1...@newsgroups.borland.com...
>> Dan Barclay wrote:
>>> Ok, I've had a problem making XML Documentation do useful tricks for me
>>> but I figured it was because I misunderstood what it was supposed to do.
>>> The docs being what they are, I really haven't had a good grip on it.
>>>
>>> However, seeing Pawel Glowacki's blog (Delphi XML Documentation Live
>>> Template) it seems clear that if I put a <summary> tag on an element, the
>>> text should show up in a tooltip when I over over a usage of the element.
>>> It simply doesn't work for me.
>>>
>>> Yes, I'm doing a full build on the project. Yup, I checked the unit.xml
>>> and the <summary> text is there.
>>>
>> <snip>
>>
>> What got me, was the summary tag has to be in the interface section, not
>> with the implementation code.
>
> AHHHGGG! I knew it would be simple. I've put it in the implementation
> section (where it should be IMHO but that's irrelevant now). OK, so WHERE
> is this info in the documentation? I'm sure it's in there somewhere but
> I've looked and it's beyond my ability to find (could be me, could be the
> docs, I'm not saying).

I "discovered" this when I was experimenting with Together, and noticed it put
those type of tags in the interface - the result of too many people using
"C-style" languages, I guess.

Anyway, I think it's very relevant. To me, the beauty of Delphi, is the
separation of the interface declarations and the implementation code. I think
this makes it very easy to see how a class is structured without having to
skip over all the code. Adding any comments in the interface makes it harder
to read, IMHO.

> My bet is that there's something else in there I'd like to know about, so
> I'd like to see it.

It would be nice if one of the CodeGear guys could blog about "the top ten
hidden Delphi features". <g>

Or better yet, document the whole darn IDE <g,d&r>.

>> and, you don't have to rebuild the soucre for the hint to show up - just
>> type in the summary text, hover over the name and the new text is in the
>> tooltip.
>
> Cool. Thanks!
>
> Dan
>

Bill

[Bill Mogk]

jrodenhi wrote:
> Well. At least this is some progress, though. I can now see my comments
> in the unit containing them. I have thought since I bought D2006 that I
> really would value this feature if it worked.
>
> I have one unit I call uCommon. I use it throughout my program because it
> has a lot of useful procedures and functions that are not part of any
> class. When I check out the uCommon.xml file, I see that the XML function
> tag shows the visibility attribute as "private". I have tried editing the
> file and changing it to "public" but it did not change the results.
>
> Do user comments show up globally for anyone in Help Insight?
>

{snip}

It's a start, I guess...

The only work-a-round, I guess, is to mouse over the item and CTRL Mouse-Click
to jump the appropriate location in the uCommon unit.

Bill

[Dan Barclay]

> FWIW, I have/get the same probelms/results as you, in this case.

OK, let's try this:

SOMEBODY HEP ME!

Dan

"Bill Mogk" <wm...@whmsoftware.com> wrote in message

news:45c27fac$1...@newsgroups.borland.com...

[Pawel Glowacki [CodeGear]]

Hi Dan,

It is also not working for me to see xml doc comments from a different unit.
I will investigate this, and if I find anything useful, I'll let you here.

-Pawel

>
> SOMEBODY HEP ME!
>

[Dan Barclay]

Thanks!

Also, it sure seems to me that the comments should live in the
implementation code instead of the interface code. If a change is needed,
perhaps they can allow it to pick up <summary> contents from either place.

Dan

"Pawel Glowacki [CodeGear]" <pawel.g...@codegear.com> wrote in message
news:45c8...@newsgroups.borland.com...

[Hans-Peter Diettrich]

Dan Barclay wrote:

> Also, it sure seems to me that the comments should live in the
> implementation code instead of the interface code. If a change is needed,
> perhaps they can allow it to pick up <summary> contents from either place.

Unlike a "class", an "interface" has no implementation, nor have fields
or properties in a class. That's why the general documentation must go
into the declaration. Further implementation specific information can be
provided with the method definitions, of course.

DoDi

[Dan Barclay]

"Hans-Peter Diettrich" <DrDiet...@aol.com> wrote in message
news:45c9309c$1...@newsgroups.borland.com...

I understand. I wasn't suggesting that they remove it from the interface,
only that they allow it to work from the implementation (where it makes
sense). I think that, for code based elements, it makes sense to have the
documentation together. As it is, the <summary> information will be with
the declaration in interface and the rest will be with the function
implementation.

Purist vs pragmatist<g>.

Dan

[davi...@netrate.com]

On Tuesday, February 6, 2007 at 6:16:32 AM UTC-5, Pawel Glowacki [CodeGear] wrote:
> Hi Dan,
>
> It is also not working for me to see xml doc comments from a different unit.
> I will investigate this, and if I find anything useful, I'll let you here.
>
> -Pawel
>

So...11 years later, did we ever get an answer to this?