Clearing cached items

Topics: Sandcastle
May 2, 2008 at 9:48 AM
Hi,

I moved one of my classes to a different namespace. Since then, SandCastle can't find the new class, and all references to its members (at least in custom topics) are rendered as bold rather than hrefs. I understand that this is an issue with SandCastle, but how can I just make it forget about the old class?

By the way, the old members keep appearing in the solution explorer, although the corresponding files are not created.

Thanks

ulu
Coordinator
May 2, 2008 at 12:29 PM
Edited May 2, 2008 at 12:31 PM
Hi ulu,

Sandcastle doesn't handle moving classes. If you change the namespace for a class then Sandcastle will treat it as an entirely different class so you must update your links manually. Make sure that all <codeEntityReference/> in conceptual content and <see cref=""/> links in XML documentation are updated to point to the new class. The new auto-generated topic will have a different GUID file name as well, although you shouldn't be linking to the GUID so it shouldn't matter.

I don't understand what you mean about members appearing in Solution Explorer. Do you mean Topic Explorer? Rebuilding the updated source project and clicking the refresh button in the Topic Explorer tool bar should fix the problem, although refreshing Topic Explorer isn't absolutely necessary anyway since the next time that you build your DocProject it will use the latest version of the project that you updated. You only need to manually refresh Topic Explorer if you want to manage filters and external XML documentation and the new class isn't shown.

If this doesn't help then please give me step by step instructions so that I can reproduce the problem :)

- Dave
May 2, 2008 at 2:59 PM
Hi Dave,

The codeEntityReference tags point to the new location indeed. I didn't expect SandCastle to replace them for me. The point is, I suspect that SandCastle keeps the old structure somewhere, and I can't figure out where. All other links work perfect, except for links to any member of the moved class.

As for the members appearing in the solution explorer in Visual Studio, this is not a problem, I just thought it might help in solving my case. When I build the project, the entries corresponding to the old members are added to the project (as in Visual Studio project), although the physical html files are not created. The new, correct entries are added as well. So, part of DocProject thinks that the old members are still there (being fooled by SandCastle I guess), while another part knows that it shouldn't create the corresponding html files.

Anyway, I still believe that this is the problem with SandCastle, not DocProject, and you probably shouldn't waste your time with it. What I need to know is where does SandCastle put the files it transforms from the xml documentation. I hope that deleting these would solve my problem.

Thanks

ulu
Coordinator
May 2, 2008 at 6:02 PM
Hi ulu,

All working files are somewhere under your project's buildhelp folder, which is hidden (do not include it as a project item). If you do a Clean or Rebuild it will remove all working files from the directory before it starts building their replacements; however, when you do a normal Build the appropriate files will get replaced anyway, so it shouldn't be necessary to clean the folder manually.

This doesn't sound like a Sandcastle issue to me, but since I can't reproduce the problem I'm not sure how to help. If there's any more information you could provide it could help me to figure out why this is happening.

A few step by step instructions may be enough, but if not then could you create a very simple test case for me? Create a new solution with a very basic source project and a new DocProject. Then create a new work item in the Issue Tracker and attach your solution as a zip file. In the work item please let me know what I need to do to reproduce the problem.

- Dave
May 3, 2008 at 6:54 PM
Oops I tried to create a test project and everything works fine of course! Gotta dig again.

ulu
Coordinator
May 3, 2008 at 9:15 PM
That's typical when reproducing strange issues :)

By the way, what versions of Visual Studio and DocProject are you using?

- Dave
May 4, 2008 at 6:57 AM
The bug was when I was using 1.10, now I'm using 1.10.1

VS 2005

ulu
May 5, 2008 at 7:23 PM
Well, I did a little research, and this is what I've found.

If I reference my class or a property of my class from a custom topic, it's rendered as a link.
But methods are rendered as if they couldn't be found (just bold text)
However, methods from the .Net library are rendered as links.
Methods of my classes, when referenced from the xml comments, are also rendered as links.

Weird.

ulu
Coordinator
May 5, 2008 at 10:14 PM
Hi ulu,

It's working fine for me using Sandcastle's Visual Studio 2005 presentation style. For example:

<para>
  A method:
  <codeEntityReference>M:TestLibrary.Types.TestClass.TestMethod(System.Object)</codeEntityReference>
</para>
<para>
  An overloaded method:
  <codeEntityReference>M:TestLibrary.Types.TestClass.TestOverload(System.Object)</codeEntityReference>
</para>
<para>
  An overloaded method without args:
  <codeEntityReference>M:TestLibrary.Types.TestClass.TestOverload</codeEntityReference>
</para>
Note that you must specify the arguments in parenthesis, if there are any.

If this doesn't help you then would you mind posting an example of the MAML that you're using?

- Dave
May 6, 2008 at 11:11 AM
Oh, I see. I didn't bother to include the argument types!

ulu
May 6, 2008 at 6:15 PM
I actually figured out how to show links to other pages.

Open the page to link to, look for the tag MSHelp:Attr Name="AssetID" and use its Value attribute. For example, I have successfully linked to a list of method overloads using <codeEntityReference>Overload:Ivonna.Framework.TestSession.ProcessPostback</codeEntityReference>
Coordinator
May 6, 2008 at 7:22 PM
Hi ulu,

Nice work. You can also find various IDs in XML documentation files and in the reflection.xml file, which is located in your project's working folder (buildhelp) after building.

- Dave