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...
Related
Coming from Java world and now learning .NET 7 development in addition, I'm embarrassed to say, I cannot figure out how to open/view relevant API Reference documentation from within the IDE.
When I right-click a Dependency (Package) in Solution Explorer, I would expect an option to open the documentation which accompanies the given NuGet package. In short: How to open this documentation? (i.e. not for a specific class, but for a package as a whole)
When I right-click a namespace in say a using Foo.Bar directive in the code editor, I would expect an option to open the documentation for Foo.Bar (show of classes, etc). I cannot find such an option.
If I hover over a class name or right-click a class I would expect an option to display documentation for that class (its description, which methods does it have?, which properties? .. and so on).
I understand as much as that the equivalent of JavaDoc is some XML stuff which is typically bundled with each NuGet package. It is basically this that I would like to browse in HTML form. Or some other form which provides me an overview of which classes and interfaces exists, their methods, cross refs, and so on.
I'm aware of the F1 option in the code editor. However, it only works for stuff which is from Microsoft (it does an MSDN search).
For all the packages I use, I can see the XML file exist on disk, so for sure it is there.
I use various third-party libraries and some of them are kind enough to publish API Reference documentation on their website .. if you can find it. It all looks slightly different in terms of skin (I can live with that), but there doesn't seem to be a convention for how this documentation is made available to the library user as I'm used to in Java world. So I need to hunt for it?
Please help a newbie.
IDE: Visual Studio CE
Language: .NET 7
I can see that this would be helpful, but what you are looking for doesn't exist. There's no centralized location for the documentation of non-microsoft packages. So if you want an overview over the classes of such a package, it's best to google for it (or visit the project's github page).
There are several ways to get to the information you want/need:
If you want to know the methods/properties of a class, just type a dot after an instance of the class to see the possible elements in a menu. If documentation exists, the description of the different methods will also be shown, together with the required parameters.
If you want to know about all the classes in a namespace, you can do the same, just explicitly type the namespace to get the list of classes.
Of course, you can also use a tool such as Ildasm or jetbrains dotPeek to get the class structure of an assembly/nuget package.
None of this is really a HTML documentation, but as said, that only exists if the package providers generate and provide it.
Basically, I developped a small library with some common fonctionnalities that I use in all my projects. For some political reasons, I cannot choose a generic name for that library (including namespace and assembly name). Usually, it must include the name of the enterprise, something like this for the namespace: Enterprise.ProjectName.XXX.YYY.
For the moment, I'm doing a copy of my library, then I'm renaming the namespaces manually with Visual Studio, and finally I'm recompiling the whole thing.
So my question is the following: Is it possible to create a small program that takes an assembly as input, rename all namespaces from MyLibrary.XXX.YYY to Enterprise.ProjectName.XXX.YYY as well as the assembly name?
What are the steps to follow?
[Edit]
Generating the assembly automatically seems to much work. I will use resharper and/or CTRL+ALT+F like I did so far. Thanks for the answers...
You could use Mono's Cecil project to disassemble the assembly, inspect each type, rename or recreate the type with a new namespace, and generate the resulting assembly.
That being said, it might be simpler to use a tool like Resharper which allows you to rename namespaces correctly within the code base.
Some options:
If you are copying the entire source code for your library into your new project, you can use a refactoring tool like Resharper to "Adjust Namespaces". This is a pretty quick and safe refactoring.
If you just need to avoid shipping the internally named assembly, you may be able to use ILMerge to 'hide' the internal assembly during a post-build step. This is viable if it's just a perception issue for the final assembly names in the binary output directory.
Deal with the issue at the political level by describing your internal library as being no different from any other third-party dependency. Then the naming is no longer a problem. This may solve other problems if you're shipping the source code of this library to multiple clients, as it clarifies that you are not giving full ownership of your 'shared' code to each client. Otherwise they could potentially argue that you are not allowed to use that 'shared' code in projects for other clients, since it is clearly owned by them, having their enterprise name in the namespace.
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.
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.
I want to define some properties on a class using the [Indexable()] attribute in order to use the class with the i4o library (http://www.codeplex.com/i4o) but when I try and compile the code Visual Studio says it cannot find the Namespace for Indexable.
Is this part of the CLR and which namespace/library do I need to get this to compile?
[Indexable()] isn't an attribute included in the .NET Framework. It was removed from i4o in favor of other approaches. See this blog post for details on how to use it.
Its not a part of the standard framework. You're going to need to identify what assembly contains this IndexableAttribute and reference it in your project.
Where is it located? I don't know. Who told you you needed to do this? Is it i4o? If so, its probably within one of the binaries that comes with the i4o project.