Is it normal I can't see xml comments from external libraries?
For example I have an external library with xml comments on methods. After making a reference to this library I was hoping that xml comments appears when I make usage of the external library; But nothing appear in the tooltip :
Maybe I have to do something special when I make the build of the lib.
First you need to enabled "XML File Documentation" generation. You can find it in the Settings of the Project under the section Build.
Then will the compiler generate an XML File containing your documentation of the assembly on build.
If you reference the assembly in another project and you want to see the documentation of types, methods, etc. in IntelliSense you need to store the xml documentation file in the same folder, where the referenced assembly is stored.
Related
My C# project (a Unity Package library) is not getting warnings on missing xmldoc of public classes, properties or methods.
I want to ensure all of my public API has XML documentation in code, but I've noticed there's undocumented public methods with no warnings. The csproj for my lib was basically copied from the csproj auto-generated by Unity, with a few changes. I'm not suppressing any warnings related to documentation as far as I can tell.
What I wanted was basically CS1591:
Missing XML comment for publicly visible type or member 'Type_or_Member'
The DocumentationFile compiler option was specified, but one or more constructs did not have comments.
It seems I have to make sure the <DocumentationFile> tag is specified to a non-empty file path (and WarningLevel 4 is not disabled) in the csproj.
<DocumentationFile>some/path/AssemblyName.xml</DocumentationFile>
I hadn't specified it before because I don't actually need documentation in a separate xml if my lib will be distributed as source code (Unity already picks the docs from code comments). I would need it if I had to compile the dll.
After specifying the DocumentationFile to some temp path, VSCode / Omnisharp will emit warnings like CS1591, CS0419.
I have a C# project with two namespaces in one solution. I've documented all the classes/functions/members/etc in both namespaces. As this project is a small research project, the namespaces are DocTestLibrary and DocTestLibrary.Events. However, when I try to create documentation from it via Sandcastle, it will only create documentation for the DocTestLibrary namespace. Is there any setting that I need to make in Sandcastle to make this work? I doubt it though, as I've scoured through most of them.
The strange thing is, Doxygen is able to generate documentation just fine.
As to provide some more information, I've checked the log that Sandcastle produces for the build.
It seems that this entry is causing the rest not to be displayed.
Warn: ResolveReferenceLinksComponent2: Unknown reference link target 'T:DocTestLibrary.Events.DemoEvent'.
I also found out something else.
The DocTestLibrary namespace consists of two classes:
TestClass
StaticHelper
As the name implies, the StaticHelper is a helper-class with only static methods. Yet Sandcastle also denies to process this file. Only the TestClass get's processed. It only boggles me that there isn't an entry about this in the log though.
In my sandcastle project it would always only include a single namespace of a total 5. The problem was that I did not check Include root namespace container under the section Help File.
Now all my namespaces are listed unter a root namespace.
Are all your types in DocTestLibrary.Events internal by any chance? By default, I believe Sandcastle only generates documentation for public types.
I've found this issue can be fixed by manually setting the classes you want documented in Edit API Filter under Project Properties -> Visibility.
It seems that this issue is fixed by setting the DocumentInternals in the Visibility properties section in the Sandcastle project. I wonder why this is, as no code is declared internal...
I guess I'll be playing around some more...
Hi kind of a newbie question.
So apparently this library is popular for this sort of thing:
http://extracting.codeplex.com/
When I download that all I get is a .dll
I can't find documentation on their api, I don't know what I'm supposed to do with this .dll (I know how to load in functions from DLLs and such, but how when I don't even know whats in it?), can someone help me out.
start a new c# project. Open the add reference dialog and use the broswe tab, select the dll.
now open the object browser - you will see all the functions etc
edit: of course you can also download the source code from codeplex; always the ultimate form of documentation
There's a link on the same page pointing to the API documentation containing sample usage.
There is a link to an example on the codeplex site
http://extracting.codeplex.com/wikipage?title=Web%20Data%20Extracting%20and%20Analyzing%20Framework%20API&referringTitle=Home
They have limited documentation on the codeplex site, available here.
I would recommend checking that documentation to see if it meets your needs, and asking any addition questions in their Discussions Page.
To use the functionality of the DLL from your project, right click on your project file in the Solution Explorer and choose "Add Reference..". You will be presented with a dialog to choose the reference you want to add. To choose the DLL from this library, browse to it from the Browse tab.
Once you've added the reference, you won't notice a whole lot of difference - all adding a reference does is give you access to the classes that are defined withing that DLL (called an "Assembly" in .NET terms). Think of it like getting a new set of "built-in" classes in your project that you can now use. You'll want to find some documentation or ask for help on the site to learn how to use these classes.
if you are using visual studio, you can just include the dll into the reference folder of your project and then use the "using" keyword to include the library into your namespace ...
If this is a .NET assembly, then reflector will tell you what classes and methods are available. You can also reference the DLL from a C# project and then press "ctrl-alt-j" to bring up the object browser to see that data inside of Visual Studio.
You can download the source code from that page.
Look at the classes and namespaces. You can add a reference to the DLL to your project and add "using" with the namespace of the DLL to the top of any code files you need to use it in in order to have access to the classes.
Additionally you can look at some of the examples posted.
Load the dll into .net Reflector. This will list the contents of the dll and any code comments associated with the API.
What is the Assembly Information File for in C# and how do I use it?
The AssemblyInfo file is used to document your dlls or exes to describe where the code comes from, its version etc. If your code is publicly available then its certainly good practice to make sure you add useful information too it.
http://www.codinghorror.com/blog/archives/000141.html
If you build your project with NAnt there is also a useful target that allows you to build the assembly info dynamically.
http://nant.sourceforge.net/release/latest/help/tasks/asminfo.html
Right-click on any program icon, and select 'Properties'. Navigate to the 'Version' tab. That information you see is what is contained in the AssemblyInfo.cs file, among other things.
It holds information about your assembly. Author, Company, Version Numbers (build/minor/major/etc)
Try this article:
http://msdn.microsoft.com/en-us/library/1h52t681.aspx
It's a file created by the default project templates under the "Properties" folder that has attributes defined at the assembly-level that the C# compiler and framework use to store various bits of metadata like the title of the assembly, the version, the publisher, etc. There's other framework-specific attributes that you can throw in there such as XAML namespaces, Data Contract namespaces, etc. Basically any attributes that you define at the assembly level are typically placed in here.
There's nothing special about the name though. These attributes can actually appear anywhere in any code file.
I posted a neat little tip about dealing with the issue of having multiple AssemblyInfo files in different projects in a solution that all have common attributes.
Is there a way to make assembly attributes show up when you right click-> Properties->details on an exe?
I know about the standard ones but I want to add my own (e.g. Email).
Edit: Also if there is a way to do this post build, that would be fine.
The information on the Version tab is retrieved from the executable's VERSIONINFO resource (we're talking native Win32 resources here, not managed resources). By default the compiler will take information from some of the Assembly attributes and put into the VERSIONINFO resource. Unfortunately you can't change which attributes the compiler uses here, so you can't include your own information this way.
But if you really want you can create your own VERSIONINFO resource and put in a .RES file and embed in your executable using the Csc.exe /win32res compiler option.
Haven't seen a pure .NET solution, but perhaps you could you combine this with this?