Start learning with our library of video tutorials taught by experts. Get started

Visual Studio 2010 Essential Training

Documenting your code


From:

Visual Studio 2010 Essential Training

with Walt Ritscher

Video: Documenting your code

Creating an external help file is a common type of documentation. Note: For this movie, I am not talking about help for the end user of the application, but rather about code documentation. This documentation is intended for other programmers to use, to get a better understanding of a code API. In order to build the Help files later in this movie, you need to install some additional open source tools. These tools are available in your Exercise File folder, in the Installers folder.
Expand all | Collapse all
  1. 2m 3s
    1. Welcome
      1m 2s
    2. Using the exercise files
      1m 1s
  2. 7m 19s
    1. Understanding the Visual Studio versions
      3m 51s
    2. Setting up your developer computer
      3m 28s
  3. 58m 2s
    1. Creating a Visual Studio project
      4m 58s
    2. Working with Solution Explorer
      6m 32s
    3. Working with big projects
      3m 53s
    4. Taking a tour of the Integrated Developer Environment (IDE)
      8m 36s
    5. Introducing drag-and-drop UI design
      7m 38s
    6. Working with the Properties window
      6m 44s
    7. Looking at Server Explorer
      7m 4s
    8. Exploring the new Help engine
      6m 41s
    9. Setting options for the IDE
      5m 56s
  4. 39m 25s
    1. Creating a simple WPF application
      1m 32s
    2. Building the UI with the editors
      9m 14s
    3. Working with the application code
      3m 37s
    4. Communicating with the web site
      7m 15s
    5. Connecting your data
      8m 4s
    6. Binding to an RSS feed
      5m 4s
    7. Packaging and deploying the application
      4m 39s
  5. 39m 46s
    1. What languages are supported in Visual Studio 2010?
      1m 17s
    2. Exploring basic settings for the Code Editor
      5m 35s
    3. Writing a C# program
      6m 48s
    4. Writing a VB program
      6m 29s
    5. Working with C++
      6m 38s
    6. Working with F Sharp
      6m 9s
    7. Font and color options
      6m 50s
  6. 1h 5m
    1. Formatting your code
      6m 43s
    2. Navigating your code
      7m 44s
    3. Using the Task List
      2m 26s
    4. Commenting your code
      2m 45s
    5. Documenting your code
      8m 26s
    6. Using IntelliSense effectively
      7m 0s
    7. Working with code snippets
      6m 25s
    8. Refactoring your code
      5m 15s
    9. Understanding code generation
      2m 10s
    10. Generating code with T4
      6m 29s
    11. Using the Class View, Class Designer, and Class Diagram tools
      5m 51s
    12. Refactoring VB with CodeRush Xpress
      4m 33s
  7. 1h 11m
    1. Working with project and item templates
      8m 38s
    2. Creating a console application
      7m 5s
    3. Creating a class library
      6m 26s
    4. Creating a web site with ASP.NET
      7m 37s
    5. Creating a rich internet application with Silverlight
      6m 57s
    6. Creating a classic Windows application with Windows Forms
      10m 31s
    7. Creating a dramatic Windows application with Windows Presentation Foundation (WPF)
      4m 41s
    8. Creating a WCF service
      9m 1s
    9. Using an existing WCF service
      6m 38s
    10. Navigation UI designs with the Document Outline view
      3m 41s
  8. 33m 18s
    1. Creating a data project with SQL Project
      6m 24s
    2. Clarifying the confusion on .NET Data
      3m 31s
    3. Using ADO.NET in your application
      6m 50s
    4. Creating typed datasets
      7m 55s
    5. Using the data binding tools
      8m 38s
  9. 30m 13s
    1. Debugging code
      9m 32s
    2. Working with the Watch and other debug windows
      7m 46s
    3. Other debugging techniques
      6m 50s
    4. IntelliTrace historical debugging in Visual Studio Ultimate
      6m 5s
  10. 17m 56s
    1. Understanding Visual Studio editions and test tools
      2m 22s
    2. Verifying your code with unit tests
      8m 58s
    3. Running performance and load tests
      6m 36s
  11. 34m 5s
    1. Building your application
      4m 19s
    2. Customizing the build process with MSBuild
      6m 36s
    3. Setting assembly information
      2m 12s
    4. Deploying a basic Windows application
      2m 19s
    5. Creating an installer with Visual Studio
      7m 39s
    6. Creating a ClickOnce application
      5m 13s
    7. Setting up IIS for deploy
      2m 9s
    8. Deploying a Silverlight or ASP.NET application
      3m 38s
  12. 14m 0s
    1. Understanding source control
      2m 9s
    2. Setting up Team Foundation Server source control
      3m 5s
    3. Using Team Foundation Server source control
      8m 46s
  13. 17m 31s
    1. Understanding the .NET Office integration
      4m 16s
    2. Making a Word 2010 application
      7m 54s
    3. Making an Excel 2010 add-in
      5m 21s
  14. 31m 34s
    1. Understanding the extensibility model in Visual Studio
      2m 17s
    2. Adding external tools to the Tools menu
      4m 42s
    3. Creating macros
      7m 16s
    4. Using the Extension Manager
      5m 1s
    5. Creating an MEF add-in
      7m 9s
    6. Deploying and installing an add-in with VSIX
      5m 9s
  15. 25m 34s
    1. Working with configuration files
      5m 37s
    2. Using the Settings Editor
      7m 30s
    3. Using the Resources Editor
      6m 59s
    4. Localizing your resources
      5m 28s
  16. 1m 17s
    1. Goodbye
      1m 17s

Watch this entire course now—plus get access to every course in the library. Each course includes high-quality videos taught by expert instructors.

Become a member
Please wait...
Visual Studio 2010 Essential Training
8h 9m Intermediate Nov 16, 2010

Viewers: in countries Watching now:

In Visual Studio 2010 Essential Training, author Walt Ritscher demonstrates how to use Visual Studio 2010 Professional to develop full-featured applications targeting a variety of platforms. Starting with an overview of the integrated developer environment, the course covers working with code editors, navigating and formatting code, and deploying applications. Also included are tutorials on running performance and load tests, and debugging code. Exercise files accompany the course.

Topics include:
  • Creating a Visual Studio project
  • Building the user interface
  • Binding to an RSS feed
  • Coding with IntelliSense
  • Creating rich Internet applications with Silverlight
  • Building Windows applications with Windows Forms
  • Integrating with SQL Server
  • Working with Microsoft Office applications
  • Understanding extensibility in Visual Studio
  • Working with data, ADO.NET and datasets
  • Using source control
Subject:
Developer
Software:
ASP.NET Silverlight Visual Studio
Author:
Walt Ritscher

Documenting your code

Creating an external help file is a common type of documentation. Note: For this movie, I am not talking about help for the end user of the application, but rather about code documentation. This documentation is intended for other programmers to use, to get a better understanding of a code API. In order to build the Help files later in this movie, you need to install some additional open source tools. These tools are available in your Exercise File folder, in the Installers folder.

There are three tools that you need to install: GhostDoc, Sandcastle, and SandcastleBuildersSetup. Sandcastle itself is the help-generation tool from Microsoft. It only works at the command line. SandcastleBuilder is a graphics interface that works with Sandcastle, and I am going to show that later in this movie. GhostDoc is a plug-in for Visual Studio that helps you write the XML comments you need. So install those and then continue with the movie. Now I am in Visual Studio. I am inside a project called BookLib, which is inside the Documenting Solution.

Both C# and Visual Basic support special help comments called XML comments. When Visual Studio encounters these XML comments, it can generate a separate XML file as part of the compile process. Then this XML file is used by the Help tools as a basis for creating the help files. My plan is to document this class here, called the Book class. So I will double-click on it. It's a simple class that has three public properties, and I see I need to make this class public for later. And then it has two methods called UpdatePrice, two overloads of the same method.

So my idea is that I want to document this method and make it easier for a developer who is using this function to know how it's going to work. What I do is I go to the line immediately above this method, and I type in three comment slashes. And you see the Visual Studio stubs in these special XML tags that are inside these three slashes. This is a summary about what this function does. So I will say, "Update the price of a book based on ID." Then I can come down here and say something about these different parameters "as a number", right? Whereas these other overload down here will have a percentage value passed into it.

Now, I am going to compile the application. It asks me if I want to save the changes. I am going to say yes. You may not see that dialog on your computer. Let's look at this from the perspective of a developer who is using this class. Over here in this code, I have instantiated an instance of the book, and I am calling UpdatePrice. Now I am going to move my cursor right here, and I am going to do a Ctrl+Shift+Spacebar, which launches the IntelliSense. You can see that it says here "Update the price of a book, based on ID." And then I am going to go over to this one, and you will see in the bottom it says, "new price as a number".

So those comments that I just wrote are now showing up in the IntelliSense for the developer that's calling my method. So you can go through your application, sprinkling useful comments in there, and you will get a much better application in the long run, for the other programmers that are using it. Now I can formalize this and put this in a Help file too, and then the user could press-- user in this case being another developer--could click on this and press F1 to launch the Help file and read more help about it. So what I need to do now is continue to add XML comments. For instance, I can come up and add them at the class level up here.

Now this can get tedious, so there is a special tool that you can add to Visual Studio, called GhostDoc. Let me show you how GhostDoc works. It's in my Tools menu, right up here at the top. That's because I installed it earlier today. I'll click on this public int ID, and then I'll go to Tools > GhostDoc and choose Document this. So this is very similar to me writing the slash, slash, slash, but the difference that GhostDoc give me is that it attempts to write something useful in here.

So it's used the value of The ID, and it's used the words "gets or sets the ID". That's the main difference in using this one. So I will do this few more times. All right, and then I will come up to the class, public class Book, like that, and now I am ready to generate my Help file. So to generate the Help file, I need to go into my project, Properties section.

Double-click on this property item over here in the Solution Explorer. I need to go to Build -- let me close this window down here in the bottom, so you can see more--and then down here in the bottom section of the Build tab, I need to check the XML documentation check box. Now when I do my compile, it's going to generate an additional XML file. Let me show you that file. I will right-click on my Project, choose Open folder in Windows Explorer. I'll go to my compile folder, which is bin > Debug, and there is my executable, and there is my XML file.

Now I am ready to make the actual Help file. To do that, I need to run that Sandcastle tool. So I am going to go out to my Start menu and type in "Sandcastle". I am using this one here, the Sandcastle Help File Builder GUI. Maximize the window. Then I will go to File > New Project. I'll put this on my Desktop, in my Exercise Files folder, Chapter 05.

You can see I have already generated some earlier today. I'll Click on Save. I am going to call this one FirstTrial. Oops! I went one folder too deep. Let me go back one folder. There we go. FirstTrial. I am nearly done. There are a couple of changes you need to make. One is you need to change your output folder. If you're storing your files in the Desktop, you cannot compile the Help file. So I need to click on this sort alphabetical, and then scroll down here to the WorkingPath. And I need to pick a folder name somewhere that won't get erased.

My C drive. And then can over here I can say BuildHere. Now what's going to happen is when I compile my Help, it's going to generate this folder, make all the files, and then when it's done it's going to erase this folder. So don't point this to any folder that you care about your files, okay? I am ready to do my Build. Now I just need to tell it where to find that XML file. So I come over here to the Documentation Sources, right-click, and choose Add Documentation Source, and then I need to go over to that bin folder I showed you a few minutes ago. Documenting > BookLib > bin, now I am going to the Debug folder.

Let's choose this XML file and click Open. At this point, I think I am ready to make the Help file. So I go to Documentation and choose Build Project. My build is done. The Help folder was generating when I did the Build. You'll see that there is a Documentation.chm file. I can run that from this folder, or I can run it from the Sandcastle build tool. I'll run it from here. And as you can see, it's a basic Help file. It shows I have a class called Book. There is my description I wrote: "An example of a Book".

I can click on this and see the syntax for the Book, and you see that it drives from System.Object. I can go over here and look at the Book methods. There are two overloads of the UpdatePrice Method. And again, my comments are showing up here. If you look at the parameters, you'll see the newPrices. The new price has a number, so that carried over. I am getting some warnings, because I haven't provided all of the information in the XML comment file, so the compiler caught this and said, "You never provided any information about that other parameter," and there are the Properties.

Creating Help is a critical part of a product lifecycle. These Help tools are good for creating help for other programmers. If you are fortunate enough to be building developer tools, then GhostDoc and Sandcastle are just the tools you need. If you are building consumer-based applications, these tools are of little value. For consumer help files, you need to investigate third-party tools.

Find answers to the most frequently asked questions about Visual Studio 2010 Essential Training.


Expand all | Collapse all
Please wait...
Q: Which edition of Visual Studio 2010 do I need to follow along in this course?
A: The course is taught with Visual Studio 2010 Professional, but can also be used with the Premium or Ultimate editions. The Express editions of Visual Studio, including Visual Basic 2010 Express, Visual C# 2010 Express, and Visual C++ Express, are not covered in this course.
Q: I'm attempting to download the exercise files for this course, and my virus protection is blocking me from unzipping the downloaded file. Are the files corrupted?
A: The alert is a false-positive message. Your antivirus software is detecting the active code included in the exercise files, which in some ways resembles viral code. There is nothing to be alarmed about and you can ignore the warning. This is common among coding courses and environments.
Share a link to this course
Please wait... Please wait...
Upgrade to get access to exercise files.

Exercise files video

How to use exercise files.

Learn by watching, listening, and doing, Exercise files are the same files the author uses in the course, so you can download them and follow along Premium memberships include access to all exercise files in the library.
Upgrade now


Exercise files

Exercise files video

How to use exercise files.

For additional information on downloading and using exercise files, watch our instructional video or read the instructions in the FAQ.

This course includes free exercise files, so you can practice while you watch the course. To access all the exercise files in our library, become a Premium Member.

Upgrade now

Are you sure you want to mark all the videos in this course as unwatched?

This will not affect your course history, your reports, or your certificates of completion for this course.


Mark all as unwatched Cancel

Congratulations

You have completed Visual Studio 2010 Essential Training.

Return to your organization's learning portal to continue training, or close this page.


OK
Become a member to add this course to a playlist

Join today and get unlimited access to the entire library of video courses—and create as many playlists as you like.

Get started

Already a member?

Become a member to like this course.

Join today and get unlimited access to the entire library of video courses.

Get started

Already a member?

Exercise files

Learn by watching, listening, and doing! Exercise files are the same files the author uses in the course, so you can download them and follow along. Exercise files are available with all Premium memberships. Learn more

Get started

Already a Premium member?

Exercise files video

How to use exercise files.

Ask a question

Thanks for contacting us.
You’ll hear from our Customer Service team within 24 hours.

Please enter the text shown below:

The classic layout automatically defaults to the latest Flash Player.

To choose a different player, hold the cursor over your name at the top right of any lynda.com page and choose Site preferencesfrom the dropdown menu.

Continue to classic layout Stay on new layout
Welcome to the redesigned course page.

We’ve moved some things around, and now you can



Exercise files

Access exercise files from a button right under the course name.

Mark videos as unwatched

Remove icons showing you already watched videos if you want to start over.

Control your viewing experience

Make the video wide, narrow, full-screen, or pop the player out of the page into its own window.

Interactive transcripts

Click on text in the transcript to jump to that spot in the video. As the video plays, the relevant spot in the transcript will be highlighted.

Thanks for signing up.

We’ll send you a confirmation email shortly.


Sign up and receive emails about lynda.com and our online training library:

Here’s our privacy policy with more details about how we handle your information.

Keep up with news, tips, and latest courses with emails from lynda.com.

Sign up and receive emails about lynda.com and our online training library:

Here’s our privacy policy with more details about how we handle your information.

   
submit Lightbox submit clicked