Merge content and API

Topics: Developer Forum
Oct 24, 2011 at 4:05 PM
Edited Oct 24, 2011 at 4:10 PM

Hello,

I am working with an open source project and I need to document it. I first created a SandCastle project and only added the project's library. Everything works fine, thanks for your work !

I now want to add comments on some of the methods of some of the classes. As the project I am working with will have releases I cannot insert my comments in the source code but have to store them in independent file(s). 

So my question: Is it possible to create additional content and have it merged with the content stored in the source code? I guess the key point is how to link my comments to the right class and method. As I cannot/do not want to edit the original source code the only valid key should be the full class name.

Ideally additional content and the source code content should be on the same page of the help file but having them on 2 different pages, as long one follows the other, should be OK.

Thanks for any help!

Coordinator
Oct 24, 2011 at 8:00 PM

I'm not sure how having releases prevents you from putting the comments in the code as it's usually the simplest way to manage the comments.  You'll still need to use an XML comments file to connect the API comments to the API members.  You can do that separately if you want to.  The member ID is used to do that.  It would be similar to managing an XML comments file for the namespace summaries (http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/52aa172a-a310-4f75-b20f-7e2c7d870c65.htm).  Also, see the FAQ topic on creating a blank XML comments file that you can fill in (See the question: I have an assembly without code and without an XML comments file for which I'd like to create documentation and/or an Intellisense file. How can I do that?).

It may be easier to manage the comments in a separate XML file and use the XML comments <include> element on the members in your code to pull in the comments from the external XML file when you build the project.  This lets you manage the comments in an XML file with IDs of your choosing but still lets you produce a standard XML comments file when your project is built.

Eric

 

Oct 25, 2011 at 7:34 AM

Hi,

"having releases prevents you from putting the comments" : Because those are my comments but the code is from a poorly documented project, it is not mine.

Same thing when you say "and use the XML comments <include> element on the members in your code": It is not my code and I will loose all <include> tags when there is a new release.

Using a separate XML file may help, I will check this.

Thanks for the support.