Some funcions in the dll are missing in the help file created

Topics: Developer Forum
Mar 9, 2010 at 12:52 PM

I have created a help file using the sand castle help file builder. After the help file is created I found some functions of the dll are not present in the help file created.

I would also like to know how to automate the help file builder for different dlls through cruise control.net

 

Please do help me out of this

Coordinator
Mar 9, 2010 at 8:09 PM

If the missing members are private and/or internal, they are not documented by default.  In order to document them, you need to set the DocumentPrivates and/or DocumentInternals project properties to True in the Visibility category.  See the Building Projects Outside the GUI topic for information on how to use MSBuild to build a SHFB project.  Using that information, you may be able to integrate the necessary commands into your own build environment.

Eric

 

Mar 10, 2010 at 10:38 AM

Hey Woodruff,

Thank you for your reply.

It helped me a lot but I am not able to see some public functions itself in the help file. I have checked the possibilities but the public functions are missing in the help file created.

 

 

Coordinator
Mar 10, 2010 at 8:41 PM

Is the class containing the members declared public and appearing in the help file?  If the class is not public, you won't see the class or any of it's public members either.  If you set DocumentPrivates and DocumentInternals to true do the members show up?  If so, then it's related to the the visiblity of the class and/or member.  You might also check to be sure that the SHFB project doesn't have an API Filter defined that is excluding the members.  If the XML comments for the missing methods have an <exclude /> comment tag, that would also cause them to be removed.

Eric

 

Mar 11, 2010 at 5:25 AM

Hi Eric,

Thank you for your help. Your suggestions are helping me a lot. Ill check all the possibilities and then let you know if I have any issues further.

I have another query Eric. I wanted to know if I can add more than one dll and documentation Xml to the Documentation Sources all at once and have the Help file created for each dll individually.

Mar 11, 2010 at 10:43 AM

Hi;

One thing I have found is that the case of the document parameter must match the case of the actual parameter 100%, otherwise the documentation for the parameter is not created.  I had exactly this same problem, which was driving me nuts until I figured it out.

Kindest Regards

Dave

Mar 11, 2010 at 12:51 PM
Edited Mar 11, 2010 at 1:01 PM

Hi,

Thank you Dave for your help.

I wanna know about to how to document the functions that are called inside the exposed functions.

I mean suppose I have a Commonfunctions.cs file and I am including it in my project and I am using it in my Assembly.

How can I document those Common functions.

Here is an example of how it looks like:

public void a()

{

commonfunctions.b();

}

 

Now how can I document the function b() in the documentation

I hope I made my issue .

Thank you,

Pradeep.

Coordinator
Mar 12, 2010 at 8:36 PM

Unless you've included the assembly containing the called methods as a documentation source and they themselves are documented, you won't see any documentation for them.  For example, if the assembly is a reference assembly, you won't see documentation for the classes and methods in the referenced assembly.  If that's what you want, you need to add the referenced assembly as a documentation source too.

Eric

 

Mar 13, 2010 at 5:47 AM

Hi,

Thank you Eric for your valuable information. This blog is really helping me out a lot. Thank you very much. Now is there a way to link the exposed function to the common function inn the documentation. I mean in the above post by me is there a way to link the documentation of commonfunctions.b(); with the documentation of the function a();

 

Thank you,

Pradeep.

Coordinator
Mar 13, 2010 at 9:51 PM

If you're asking if there's a way in the XML comments for method A to link to the comments for method B, the <see> or <seealso> XML comments tag will do that.  However, you do need to include the assembly containing method B as a documentation source.  If you are not familiar with the available XML comments tags, see the XML Comments Guide.

Eric

 

Mar 17, 2010 at 8:56 AM
Edited Mar 17, 2010 at 4:18 PM

Hi Eric,

I have tried out with commenting the Common functions by the way you suggested but it did not work out for me.

        /// <code>GetDMSListing</code> This funtion is used to get the DMSListing. It calls the OrchCommonFunctions.GetDMSListing
        /// See <see cref="OrchCommonFunctions.GetDMSListing">OrchCommonFunctions.GetDMSListing</see> for further information
        /// </summary>  

 

/// <summary>

///  This is description for function A() of Test.cs

        /// See <see cref="CommonFunctions.B">CommonFunctions.B</see> for further information

/// </summary>  

I gave this comments at the exposed function Sample().

I have also attached the CommonFunctions.cs to the documentation source along with the Test.dll and Test.xml and built the help file.

But i'm not able to find any documentation for the function B() or any functions in the CommonFunctions.cs.

Here the Commonfunctions.cs does not exist in the same folder structure where the Test.dll exists.

It is added to the Test assembly by browsing to the folder structure using Add an Exisiting Item

I'm able to find the .htm files created for the members of CommonFunctions.cs in the html folder in the Output folder. But there is no link between the Test class members and the CommonFunctions class members.

Is there any attribute that is to be set to true.

I request you to please help me out of this.

If possible can you illustrate me with an example. 

Regards,

Pradeep.

 

 

Coordinator
Mar 17, 2010 at 4:02 PM

It would be better if you could send me a small example that demonstrates what you are trying to do and what isn't working.  My e-mail address is in the About box in the GUI and in the footer of the pages in the help file.

Eric

 

Mar 19, 2010 at 5:46 AM

Eric,

Hi Eric I have sent you a mail regarding the issue, but I have not received any response from you. So I'm updating the status over here.

The problem with the issue I have posted above is Name-spaces.

As per the above example, say CommonFunctions class is under the name-space Sample1 and the Test class is under the name-space Sample2. 

As the name-spaces are different <see cref="CommonFunctions.B"> is not working in the comments of function A() .

Now if the name-spaces are same it works.

Please let me know about how to link the CommonFunctions.B() to Test.B(), the namespaces being different.

 

Mar 24, 2010 at 5:39 AM
Edited Mar 24, 2010 at 5:41 AM

Hi Eric,

While adding the <see cref=""/> tags to link another function, I have come with a problem. I'm not clear about how to call two overloaded function through <see> tag.

I mean, suppose there are two functions say 

a.cs

class zzz

{

void abc(int i)

{

}

void abc( out int i)

{

i = 10;

}

void abc( ref int i)

{

}

public static void  Main()

{

}

}

 

Now how can we give <see> tags the functions abc(int), abc(out int), abc(ref int) respectively.

 

Thank you,

Pradeep.

Coordinator
Mar 24, 2010 at 8:25 PM

You need to specify the overload to which to link such as <see cref="abc(int)" />.  The other two for that take the ref and out parameters should be similar but include the ref or out keyword but I don't recall for sure.

Eric

 

Mar 29, 2010 at 10:51 AM

Thank you Eric. Your solution has helped me out. 

Now I'm building the documentation for 2 or more dlls with the same Help file builder project. I mean to say that for the same .shfbproj I'm adding two different and independent dlls as the Documentation Sources and generating the documentation. Now is there any way to link the documentation of the two dlls i.e provide link for dll1 in the documentation of dll2 like See or Seealso etc.......

I hope I made it clear.

I would also like to know if any check is possible to know if documentation(Comments) are added or not  to the Functions in the dll if I have to automate the documentation process.

Regards,

Pradeep.

Coordinator
Mar 29, 2010 at 4:59 PM

You should be able to use a <see> or <seealso> that links to the namespace to show all types within a namespace.  Once in the help file, they are not grouped by assembly so unless the namespaces are unique to the assembly, you can't get a list of stuff in just one assembly.  The project properties in the Show Missing Tags category control which elements in the API topics are flagged as missing if not present in the XML comments.  Warnings are generated in the build log and the help file topics contain warning messages that you can search for to find topics containing missing elements.  See the Show Missing Tags help topic for more information.

Eric

 

Mar 30, 2010 at 8:13 AM

Eric,

I am adding some custom tags like <Session check  = "yes"/> for all the exposed functions of a dll.

Now I need to enable a message like [Missing <Session check> tag for "F:Orchestra.IVersionChecker.versionArr"] if the cutom tag is not added in the documentation(comments xml). How can I do this.

Please help me out on this.

Regards,

Pradeep.


Coordinator
Mar 30, 2010 at 8:20 PM
Edited Mar 30, 2010 at 8:21 PM

The build component only checks for the standard XML comment elements.  You'll either need to create your own build component to check for your custom XML comment tags or, assuming you're using them in the Sandcastle transformations, modify the transformations to output the warning if the element is not found.

Eric