Have a question? Email Us or Call 1 (800) 936-2134
SubMain - CodeIt.Right The First Time! Home Products Services Download Purchase Support Community
 Tuesday, 03 January 2017

Last month, I wrote a post introducing you to T4 templates.  Near the end, I included a mention of GhostDoc's use of T4 templates in automatically generating code comments.  Today, I'd like to expand on that.

To recap very briefly, recall that Ghost Doc allows you to generate things like method header comments.  I recommend that, in most cases, you let it do its thing.  It does a good job.  But sometimes, you might have occasion to want to tweak the result.  And you can do that by making use of T4 Templates.

Documenting Chess TDD

To demonstrate, let's revisit my trusty toy code base, Chess TDD.  Because I put this code together for instructional purposes and not to release as a product, it has no method header comments for IntelliSense's benefit.  This makes it the perfect candidate for a demonstration.

If I had released this as a library, I'd have started the documentation with the Board class.  Most of the client interaction would happen via Board, so let's document that.  It offers you a constructor and a bunch of semantics around placing and moving pieces.  Let's document the conceptually simple MovePiece method.

public void MovePiece(BoardCoordinate origin, BoardCoordinate destination)
{
    VerifyCoordinatesOrThrow(origin, destination);

    var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination);
    RemovePiece(origin);
    pieceToMove.HasMoved = true;

    ReconcileEnPassant(origin, destination, pieceToMove);
}

To add documentation to this method, I simply right click it and, from the GhostDoc context menu, select "Document This."  Alternatively, I can use the keyboard shortcut Ctrl-Shift-D.  Either option yields the following result.

/// <summary>
/// Moves the piece.
/// </summary>
/// <param name="origin">The origin.</param>
/// <param name="destination">The destination.</param>
public void MovePiece(BoardCoordinate origin, BoardCoordinate destination)
{
    VerifyCoordinatesOrThrow(origin, destination);

    var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination);
    RemovePiece(origin);
    pieceToMove.HasMoved = true;

    ReconcileEnPassant(origin, destination, pieceToMove);
}

Let's Make a Tiny Tweak

Alright, much better!  If I scrutinize the comment, I can imagine what an IntelliSense-using client will see.  My parameter naming makes this conceptually simple to understand, so the IntelliSense will tell the user that the first parameter represents the origin square and the second parameter the destination.

But let's say that as I look at this, I find myself wanting to pick at a nit.  I don't care for the summary taking up three lines -- I want to condense it to one.  How might I do that?

Well, let's crack open the T4 template for generating a method header.  Recall that you do this in Visual Studio by selecting Tools->Ghost Doc->Options, and picking "Rules" from the options pane.

blog-intro-to-t4-templates-part2-1

If you double click on "Method Template", as highlighted above, you will see an "Edit Rule" Window.  The first few lines of code in that window look like this.

<#@ template language="C#" #>
<#  CodeElement codeElement = Context.CurrentCodeElement; #>
/// <summary>
///<# GenerateSummaryText(); #>
/// </summary>
<#    if(codeElement.HasTypeParameters) 
    {
        for(int i = 0; i < codeElement.TypeParameters.Length; i++) 
        { 
            TypeParameter typeParameter = codeElement.TypeParameters[i]; 
#>

Hmmm.  I cannot count myself an expert in T4 templates, per se, but I think I have an idea.  Let's put that call to GenerateSummaryText() inline between the summary tags.  Like this:

<#@ template language="C#" #>
<#  CodeElement codeElement = Context.CurrentCodeElement; #>
/// <summary><# GenerateSummaryText(); #></summary>

That should do it, right?  Let's regenerate the comment and see what it looks like.  This results in the following.

/// <summary>Moves the piece.
/// </summary>
/// <param name="origin">The origin.</param>
/// <param name="destination">The destination.</param>
public void MovePiece(BoardCoordinate origin, BoardCoordinate destination)
{
    VerifyCoordinatesOrThrow(origin, destination);

    var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination);
    RemovePiece(origin);
    pieceToMove.HasMoved = true;

    ReconcileEnPassant(origin, destination, pieceToMove);
}

Uh, oh.  It made a difference, but somehow we only got halfway there.  Why might that be?

Diving Deeper

To understand, we need to look at the template in a bit more detail.  The template itself has everything on one line, and yet we see a newline in there somehow.  Could GenerateTextSummary cause this, somehow?  Let's scroll down to look at it.  Since this method has a lot of code, here are the first few lines only.

private void GenerateSummaryText()
{
    if(Context.HasExistingTagText("summary"))
    {
        this.WriteLine(Context.GetExistingTagText("summary"));
    }
    else if(IsAsyncMethod())
    {
        this.WriteLine(Context.ExecMacro("$(MethodName.Words.ExceptLast)") + " as an asynchronous operation.");
    }
    else if(IsMainMethod())
    {
        this.WriteLine("Defines the entry point of the application.");        
    }
}

Aha!  Notice that we're calling WriteLine.  What if we did a find and replace to change all of those to just Write?  Let's try.  (To do more serious operations like this, you will want to copy the text out of the editor and into your favorite text editor in order to get more operations).

Once you have replaced all instances of WriteLine with Write in the template, here is the new result.

/// <summary>Moves the piece.</summary>
/// <param name="origin">The origin.</param>
/// <param name="destination">The destination.</param>
public void MovePiece(BoardCoordinate origin, BoardCoordinate destination)
{
    VerifyCoordinatesOrThrow(origin, destination);

    var pieceToMove = GetPiece(origin);
    AddPiece(pieceToMove, destination);
    RemovePiece(origin);
    pieceToMove.HasMoved = true;

    ReconcileEnPassant(origin, destination, pieceToMove);
}

Success!

Validation

As you play with this, you might have noticed a "Validate" button in the rule editor.  Use this liberally!  This button will trigger a parsing of the template and provide you with feedback as to validity.  The last thing you want to do is work in here for many iterations and wind up with no idea what you broke and when.

When working with these templates, think of this as equivalent to compiling.  You wouldn't want to sit for 20 minutes writing code with no feedback as to whether it builds or not.  So don't do it with these templates.

The Power at Your Disposal

I'll wrap here for this particular lesson, but understand that we have barely scratched the surface of what you can do.  In this post, we just changed a bit of the formatting to suit a whim I had.  But you can really dive into ways of reasoning about and documenting the code if you so choose.

Stay tuned for future posts on more advanced tips and tricks with your comment templates.

Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Tuesday, 03 January 2017 10:47:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Tuesday, 22 November 2016

Today, I'd like to tackle a subject that inspires ambivalence in me.  Specifically, I mean the subject of automated text generation (including a common, specific flavor: code generation).

If you haven't encountered this before, consider a common example.  When you file->new->(console) project, Visual Studio generates a Program.cs file.  This file contains standard includes, a program class, and a public static void method called "Main."  Conceptually, you just triggered text (and code) generation.

Many schemes exist for doing this.  Really, you just need a templating scheme and some kind of processing engine to make it happen.  Think of ASP MVC, for instance.  You write markup sprinkled with interpreted variables (i.e. Razor), and your controller object processes that and spits out pure HTML to return as the response.  PHP and other server side scripting constructs operate this way and so do code/text generators.

However, I'd like to narrow the focus to a specific case: T4 templates.  You can use this powerful construct to generate all manner of text.  But use discretion, because you can also use this powerful construct to make a huge mess.  I wrote a post about the potential perils some years back, but suffice it to say that you should take care not to automate and speed up copy and paste programming.  Make sure your case for use makes sense.

The Very Basics

With the obligatory disclaimer out of the way, let's get down to brass tacks.  I'll offer a lightning fast getting started primer.

Open some kind of playpen project in Visual Studio, and add a new item.  You can find the item in question under the "General" heading as "Text Template."

blog-intro-to-t4-templates-part1-1

Give it a name.  For instance, I called mine "sample" while writing this post.  Once you do that, you will see it show up in the root directory of your project as Sample.tt.  Here is the text that it contains.

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".txt" #>

Save this file.  When you do so, Visual Studio will prompt you with a message about potentially harming your computer, so something must be happening behind the scenes, right?  Indeed, something has happened.  You have generated the output of the T4 generation process.  And you can see it by expanding the caret next to your Sample.tt file as shown here.

blog-intro-to-t4-templates-part1-2

If you open the Sample.txt file, however, you will find it empty.  That's because we haven't done anything interesting yet.  Add a new line with the text "hello world" to the bottom of the Sample.tt file and then save.  (And feel free to get rid of that message about harming your computer by opting out, if you want).  You will now see a new Sample.txt file containing the words "hello world."

Beyond the Trivial

While you might find it satisfying to get going, what we've done so far could be accomplished with file copy.  Let's take advantage of T4 templating in earnest.  First up, observe what happens when you change the output extension.  Make it something like .blah and observe that saving results in Sample.blah.  As you can see, there's more going on than simple text duplication.  But let's do something more interesting.

Update your Sample.tt file to contain the following text and then click save.

<#@ template debug="false" hostspecific="false" language="C#" #>
<#@ assembly name="System.Core" #>
<#@ import namespace="System.Linq" #>
<#@ import namespace="System.Text" #>
<#@ import namespace="System.Collections.Generic" #>
<#@ output extension=".txt" #>
<#
for(int i = 0; i < 10; i++)
    WriteLine($"Hello World {i}");
#>

When you open Sample.txt, you will see the following.

Hello World 0
Hello World 1
Hello World 2
Hello World 3
Hello World 4
Hello World 5
Hello World 6
Hello World 7
Hello World 8
Hello World 9

Pretty neat, huh?  You've used the <# #> tokens to surround first class C# that you can use to generate text.  I imagine you can see the potential here.

Oh, and what happens when you type malformed C#?  Remove the semicolon and see for yourself.  Yes, Visual Studio offers you feedback about bad T4 template files.

Use Cases

I'll stop here with the T4 tutorial.  After all, I aimed only to provide an introduction.  And I think that part of any true introduction involves explaining where and how the subject might prove useful to readers.  So where do people reasonably use these things?

Perhaps the most common usage scenario pertains to ORMs and the so-called impedance mismatch problem.  People create code generation schemes that examine databases and spit out source code that matches with them.  This approach spares the significant performance hit of some kind of runtime scheme for figuring this out, but without forcing tedious typing on dev teams.  Entity Framework makes use of T4 templates.

I have seen other uses as well, however.  Perhaps your organization puts involved XML configuration files into any new projects and you want to generate these without copy and paste.  Or, perhaps you need to replace an expensive reflection/runtime scheme for performance reasons.  Maybe you have a good bit of layering boilerplate and object mapping to do.  Really, the sky is the limit here, but always bear in mind the caveat that I offered at the beginning of this post.  Take care not to let code/text generation be a crutch for cranking out anti-patterns more rapidly.

The GhostDoc Use Case

I will close by offering a tie-in with the GhostDoc offering as the final use case.  If you use GhostDoc to generate comments for methods and types in your codebase, you should know that you can customize the default generations using T4 templates.  (As an aside, I consider this a perfect use case for templating -- a software vendor offering a product to developers that assists them with writing code.)

If you open GhostDoc's options pane and navigate to "Rules" you will see the following screen.  Double clicking any of the templates will give you the option to edit them, customizing as you see fit.

blog-intro-to-t4-templates-part1-3

You can thus do simple things, like adding some copyright boilerplate, for instance.  Or you could really dive into the weeds of the commenting engine to customize to your heart's content (be careful here, though).  You can exert a great deal of control.

T4 templates offer you power and can make your life easier when used judiciously.  They're definitely a tool worth having in your tool belt.  And, if you make use of GhostDoc, this is doubly true.

Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Tuesday, 22 November 2016 09:23:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Monday, 21 November 2016

Version 5.4 of GhostDoc is a maintenance update for the v5.0 users:

  • VS2017 RC integration
  • New menu items - Getting Started Tutorial and Tutorials and Resources
  • (Pro) (Ent) Edit buttons in Options - Solution Ignore List and Options - Spelling Ignore List
  • (Pro) (Ent) Test button in Options - Solution Ignore List
  • (Ent) Now GhostDoc shows error message when Conceptual Content path is invalid in the solution configuration file
  • Fixed PathTooLongException exception when generating preview/build help file for C++ projects
  • (Ent) Updated ClassLibrary1.zip, moved all conceptual content files inside the project in GhostDoc Enterprise\Samples\Conceptual Content\
  • Improved documenting ReadOnly auto-properties in VB
  • Resolved issue re-documenting a type at the top of source code file in VB
  • Resolved issue with generating preview of the <seealso> tag for generics in VB

For the complete list of changes, please see What's New in GhostDoc v5

For overview of the v5.0 features, visit Overview of GhostDoc v5.0 Features

Download the new build at http://submain.com/download/ghostdoc/

posted on Monday, 21 November 2016 09:15:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Wednesday, 16 November 2016

We are looking for your input and we're willing to bribe you for answering one very simple question: What are your biggest code documentation challenges right now?

The survey is super-quick and we're offering a $20 discount code for your time (good with any new SubMain product license purchase) that you will automatically receive once you complete the survey as our thank you.

Take the Survey

We'd also appreciate it if you'd help us out by tweeting about this using the link Share on Twitter or otherwise letting folks know we're interested to know their code documentation challenges.

Thanks for your help!

posted on Wednesday, 16 November 2016 09:23:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Tuesday, 25 October 2016

If you spend enough years writing software, sooner or later, your chosen vocation will force you into reverse engineering.  Some weird API method with an inscrutable name will stymie you.  And you'll have to plug in random inputs and examine the outputs to figure out what it does.

blog-elements-of-helpful-code-documentationClearly, this wastes your time.  Even if you enjoy the detective work, you can't argue that an employer or client would view this as efficient.  Library and API code should not require you to launch a mystery investigation to determine what it does.

Instead, such code should come with appropriate documentation.  This documentation should move your focus from wondering what the code does to contemplating how best to leverage it.  It should make your life easier.

But what constitutes appropriate documentation?  What particular characteristics does it have?  In this post, I'd like to lay out some elements of helpful code documentation.

Elements of Style

Before moving on to what the documentation should contain, I will speak first about its stylistic properties.  After all, poorly written documentation can tank understanding, even if it theoretically contains everything it should.  If you're going to write it, make it good.

Now don't get me wrong -- I'm not suggesting you should invest enough time to make it a literary masterpiece.  Instead, focus on three primary characteristics of good writing: clarity, correctness, and precision.  You want to make sure that readers understand exactly what you're talking about.  And, obviously, you cannot get anything wrong.

The importance of this goes beyond just the particular method in question.  It affects your entire credibility with your userbase.  If you confuse them with ambiguity or, worse, get something wrong, they will start to mistrust you.  The documentation becomes useless to them and your reputation suffers.

Examples

Once you've gotten your house in order with stylistic concerns in the documentation, you can decide on what to include.  First up, I cannot overstate the importance of including examples.

Whether you find yourself documenting a class, a method, a web service call, or anything else, provide examples.  Show the users the code in action and let them apply their pattern matching and deduction skills.  In case you hadn't noticed, programmers tend to have these in spades.

Empathize with the users of your code.  When you find yourself reading manuals and documentation, don't you look for examples?  Don't you prefer to grab them and tweak them to suit your current situation?  So do the readers of your documentation.  Oblige them. (See <example />)

Conditions

Next up, I'll talk about the general consideration of "conditions."  By this, I mean three basic types of conditions: preconditions, postconditions, and invariants.

Let me define these in broad terms so that you understand what I mean.  Respectively, preconditions, postconditions, and invariants are things that must be true before your code executes, things that must be true after it executes, and things that must remain true throughout.

Documenting this information for your users saves them trial and error misery.  If you leave this out, they may have to discover for themselves that the method won't accept a null parameter or that it never returns a positive number.  Spare them that trial and error experimentation and make this clear.  By telling them explicitly, you help them determine up front whether this code suits their purpose or not. (See <remarks /> and <note />)

Related Elements

Moving out from core principles a bit, let's talk about some important meta-information.  People don't always peruse your documentation in "lookup" mode, wanting help about a code element whose name they already know.  Instead, sometimes they will 'surf' the documentation, brainstorming the best way to tackle a problem.

For instance, imagine that you want to design some behavior around a collection type.  Familiar with List, you look that up, but then maybe you poke around to see what inherits from the same base or implements the same interface.  By doing this, you hope to find the perfect collection type to suit your needs.

Make this sort of thing easy on readers of your documentation by offering a concept of "related" elements.  Listing OOP classes in the same hierarchy represents just one example of what you might do.  You can also list all elements with a similar behavior or a similar name.  You will have to determine for yourself what related elements make sense based on context.  Just make sure to include them, though. (See <seealso /> )

Pitfalls and Gotchas

Last, I'll mention an oft-overlooked property of documentation.  Most commonly, you might see this when looking at the documentation for some API call.  Often, it takes the form of "exceptions thrown" or "possible error codes."

But I'd like to generalize further here to "pitfalls and gotchas."  Listing out error codes and exceptions is great because it lets users know what to expect when things go off the rails.  But these aren't the only ways that things can go wrong, nor are they the only things of which users should be aware.

Take care to list anything out here that might violate the principle of least surprise or that could trip people up.  This might include things like, "common ways users misuse this method" or "if you get output X, check that you set Y correctly."  You can usually populate this section pretty easily whenever a user struggles with the documentation as-is.

Wherever you get the pitfalls, just be sure to include them.  Believe it or not, this kind of detail can make the difference between adequate and outstanding documentation.  Few things impress users as much as you anticipating their questions and needs. (See <exception />, <returns /> and <remarks />)

Documentation Won't Fix Bad Code

In closing, I would like to offer a thought that returns to the code itself.  Writing good documentation is critically important for anyone whose code will be consumed by others -- especially those selling their code.  But it all goes for naught should you write bad or buggy code, or should your API present a mess to your users.

Thus I encourage you to apply the same scrutiny to the usability of your API that I have just encouraged you to do for your documentation.  Look to ensure that you offer crisp, clear abstractions.  Name code elements appropriately.  Avoid surprises to your users.

Over the last decade or so, organizations like Apple have moved us away from hefty user manuals in favor of "discoverable" interfaces.  Apply the same principle to your code.  I tell you this not to excuse you from documentation, but to help you make your documentation count.  When your clean API serves as part of your documentation, you will write less of it, and what you do write will have higher value to readers.

Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Tuesday, 25 October 2016 10:53:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 06 October 2016

Before I get down to the brass tacks of how to do some interesting stuff, I'm going to spin a tale of woe.  Well, I might have phrased that a little strongly.  Call it a tale of corporate drudgery.

In any case, many years ago I worked briefly in a little department, at a little company that seemed to be a corporate drudgery factory.  Oh, the place and people weren't terrible.  But the work consisted of, well, drudgery.  We 'consulted' in the sense that we cranked out software for other companies, for pay.  Our software plumbed the lines of business between client CRMs and ERPs or whatever.  We would write the software, then finish the software, then hand the software over, source code and all.

Naturally, commenting our code and compliance with the coding standard attained crucial importance.  Why?  Well, no practical reason.  It was just that clients would see this code.  So it needed to look professional.  Or something.  It didn't matter what the comments said.  It didn't matter if the standard made sense.  Compliance earned you a gold star and a move onto the next project.

As I surveyed the scene surrounding me, I observed a mountain of vacuous comments and dirty, but uniform code.

My Complex Relationship with Code Comments

My brief stay with (and departure from) this organization coincided with my growing awareness of the Software Craftsmanship movement.  Even as they copy and pasted their way toward deadlines and wrote comments announcing that while(x < 6) would proceed while x was less than 6, I became interested in the idea of the self-documenting code.

Up to that point, I had diligently commented each method, file, and type I encountered.  In this regard, I looked out for fellow and future programmers.  But after one too many occasions of watching my own comments turn into lies when someone changed the code without changing the comments, I gave up.  I stopped commenting my code, focusing entirely on extractions, refactoring, and making my code as legible as possible.

I achieved an equilibrium of sorts.  In this fashion, I did less work and stopped seeing my comments become nasty little fibs.  But a single, non-subtle flaw remained in this absolutist approach.  What about documentation of a public (or internal) API?

Naturally, I tried to apply the craftsmanship-oriented reasoning unilaterally.  Just make the public API so discoverable as to render the issue moot.  But that never totally satisfied me because I still liked my handy help screens and IntelliSense info when consuming others' code.

And so I came to view XML doc comments on public methods as an exception.  These, after all, did not represent "comments."  They came packaged with your deliverables as your product.  And I remain comfortable with that take today.

Generating Help More Efficiently

Now, my nuanced evolved view doesn't automatically mean I'll resume laboriously hand-typing XML comments.  Early in my career, a sort of sad pride in this "work harder, not smarter" approach characterized my development.  But who has time for that anymore?

Instead, with a little bit of investment in learning and tooling, you can do some legitimately cool stuff.  Let me take you through a nifty sequence of steps that you may come to love.

GhostDoc Enterprise

First up, take a look at the GhostDoc Enterprise offering.    Among other things, this product lets you quickly generate XML comments, customize the default generation template, spell check your code, generate help documentation and more.  Poking through all that alone will probably take some time out of your day.  You should download and play with the product.

Once you are done with that, though, consider how you might get more efficient at beefing up your API.  For the rest of this post, I will use as an example my Chess TDD project.  I use this as a toy codebase for all kinds of demos.

I never commented this codebase, nor did I generate any kind of documentation for it.  Why?  I intended it solely as a teaching tool for test-driven development, and never packaged it for others' consumption.  Let's change that today.

Adding Comments

Armed with GhostDoc enterprise, I will first generate some comments.  The Board class makes a likely candidate since that offers theoretical users the most value.

First up, I need to add XML doc comments to the file.  I can do this by right clicking in the file, and selecting "Document Type" from the GhostDoc Enterprise context menu.  Here's what the result looks like.

blog-generate-docs-from-your-build-1

The default template offers a pretty smart guess at intent, based on good variable naming.  For my fellow clean code enthusiasts out there, you can even check how self-documenting your code is by the quality of the comments GhostDoc creates.  But still, you probably want to take a human pass through, checking and tweaking where needed.

Building Help Documentation

All right.  With comments in place for the public facing API of my little project, we can move on to the actual documentation.  Again, easy enough.  Select "Tools -> GhostDoc Enterprise -> Build Help Documentation" from the main menu.  You'll see this screen.

blog-generate-docs-from-your-build-2

Notice that you have a great deal of control over the particulars.  Going into detail here is beyond the scope of my post, but you can certainly play around.  I'll take the defaults and build a CHM help file.  Once I click "OK", here's what I see (once I go to the board class).

blog-generate-docs-from-your-build-3

Pretty slick, huh?  Seriously.  With just a few clicks, you get intelligently commented public methods and a professional-looking help file.  (You can also have this as web-style documentation if you want).  Obviously, I'd want to do some housekeeping here if I were selling this, but it does a pretty good job even with zero intervention from me.

Do It From the Build

Only one bit of automation remains at this point.  And that's the generation of this documentation from the build.  Fortunately, GhostDoc Enterprise makes that simple as well.

Any build system worth its salt will, of course, let you hook command line invocations into your build.  GhostDoc Enterprise offers one up for just this occasion.  You can read a succinct guide on that right here.  With a single command, you can point it at your solution, a help configuration, and a project configuration, and generate the help file.  Putting it where you want is then easy enough.

Tying this in with an automated build or CI setup really ties everything together, including the theme of this post.  Automating the generation of clean, helpful documentation of your clean code, building it, and packaging it up all without human intervention pretty much represents the pinnacle of delivering a professional product.

Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Thursday, 06 October 2016 06:54:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Friday, 16 September 2016

Version 5.3 of GhostDoc is a maintenance update for the v5.0 users:

  • Added full support for string interpolation in C# and VB parsers
  • Added support for "arrow functions" in JavaScript parser
  • Fixed "File is not part of a solution" issue when loading projects
  • (Pro) (Ent) Added IsAbstract property to CurrentCodeElement in the T4 templates
  • Improved exception documentation - now the type name in a nameof() parameter is added as part of the generated documentation template
  • (Ent) Fixed iue when using <section> along with <code> elements in an .aml file

For the complete list of changes, please see What's New in GhostDoc v5

For overview of the v5.0 features, visit Overview of GhostDoc v5.0 Features

Download the new build at http://submain.com/download/ghostdoc/

posted on Friday, 16 September 2016 08:30:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Wednesday, 14 September 2016

Think back to college (or high school, if applicable).  Do you remember that kid that would sit near the front of the class and gleefully point out that the professor had accidentally omitted an apostrophe when writing notes on the white board?  Didn't you just love that kid?  Yeah, me neither.

Fate imbues a small percentage of the population with a neurotic need to correct any perceived mistakes made by anyone.  XKCD immortalized this phenomenon with one of its most famous cartoons, that declared, "someone is wrong on the internet."  For the rest of the population, however, this tendency seems pedantic and, dare I say, unpleasant.  Just let it go, man.  It doesn't matter that much.

I mention all of this to add context to the remainder of the post.  I work as a consultant and understand the need for diplomacy, tact, and choosing one's battles.  So, I do not propose something like care with spelling lightly.  But I will propose it, nonetheless.

Now I know what you're thinking.  How can caring about spelling in code be anything but pedantic?  We're not talking about something being put together to impress a wide audience, like a newspaper.  In fact, we're not even talking about prose.  And code contains all sorts of abbreviations and encodings and whatnot.

Nevertheless, it matters.  When English words occur in your code, spelling them right matters.  I'll use the rest of this post to make my case.

The IntelliSense Conundrum

If you use Visual Studio, no doubt you make heavy use of IntelliSense.  To expand, any IDE or text editor with autocomplete functionality qualifies for consideration here.  In either case, your tooling gives you a pretty substantial boost by suggesting methods/variables/classes/etc based on what you have typed.  It's like type-ahead for code.

Now think of the effect a misspelling can have here, particularly near the beginning of a word.  Imagine implementing a method that would release resources and accidentally typing Colse instead of Close.  Now imagine consuming that method.  If you're used to exploring APIs and available methods with auto-complete, you might type, "Clo", pause, and see no matching methods.  You might then conclude, "hey, no call to Close needed!"

In all likelihood, such an error would result in a few minutes of head-scratching and then the right call.  But even if that's the worst of it, that's still not great.  And it will happen each and every time someone uses your code.

Other Manual Typing Errors

The scope of this particular issue goes beyond auto-complete functionality.  Perhaps you lack that functionality in your environment, or perhaps you simply don't use it much.  In that case, you'll be hand typing your code.

Now, imagine hand typing the call above to a close method.  Do you instinctively type "Colse" or do you instinctively type "Close?"  So what do you think will happen?

You'll expect the call to be Close and you'll type that.  Then, you'll stare in disbelief for a moment at the compiler message.  You'll probably do a clean and rebuild.  You'll stare again for a while and squint.  Then, finally, you'll smack your forehead, realize the problem, and silently berate the person who misspelled the method name.

Again, the impact remains the same.  Most likely this creates only friction and annoyance.  Every now and then, it may trigger a thoroughly incorrect use of a library or API.

Anchoring Effect

Moving away from the theme of confusion when using a declared member, consider the declaration itself.  During the use of a variable/method/class/etc, you must spell it right before the compiler allows you to proceed (assuming a strongly typed language).  With the original declaration, however, you have the freedom to spell things wrong to your heart's content.  When you do this, the original copy holds the error.

That first misspelling allows for easy correction.  Same goes when you've used it only a time or two.  But as usage grows and spreads throughout the codebase, the fix becomes more and more of a chore.  Before long (and without easy refactoring tools), the chore becomes more than anyone feels like tackling, and the error calcifies in place.

Your unaddressed spelling mistake today makes fixes more difficult tomorrow.

Comprehension Confusion

Let's switch gears again and consider the case of a maintenance programmer reading for comprehension.  After all, programmers do a whole lot more reading of code than they do modification of it.  So, a casual read is a likely situation.

Spelling errors cloud comprehension.  A simple transposition of characters or a common error, such as referring to a "dependency" do not present an insurmountable problem.  But a truly mangled word can leave readers scratching their heads and wondering what the code actually means, almost as if you'd left some kind of brutal Hungarian notation in there.

Taking the time to get the spelling right ensures that anyone maintaining the code will not have this difficulty.  Code is hard enough to understand, as-is, without adding unforced errors to the mix.

The Embarrassment Factor

And, finally, there's the embarrassment factor.  And I don't mean the embarrassment of your coworkers saying, "wow, that guy doesn't know how to spell!"  I'm talking about the embarrassment factor for the team.

Think of new developers hiring on or transferring into the group.  They're going to take a look at the code and draw conclusions, about your team.  Software developers tend to have exacting, detail-oriented minds, and they tend to notice mistakes.  Having a bunch of spelling mistakes in common words makes it appear either that the team doesn't know how to spell or that it has a sloppy approach.  Neither of those is great.

But also keep in mind that what happens in the code doesn't always stay in the code.  Bits of the code you write might appear on team dashboards, build reports, unit test run outputs, etc.  People from outside of the team may be examining acceptance tests and the like.  And, you may have end-user documentation generated automatically using your code (i.e. if you make developer tools or APIs).  Do you really want the documentation you hand to your customers to contain embarrassing mistakes?

It's Easy to Get Right

At this point, I'm finished with the supply of arguments for making the case.  I've laid these out.

But, by way of closing words, I'd like to comment on what might be the biggest shame of the whole thing.  Purging your code of spelling errors doesn't require you to be an expert speller.  It doesn't require you to copy source code into MS Word or something and run a check.  You have tools at your disposal that will do this for you, right in your IDE.  All you need to do is turn them on.

I recommend that you do this immediately.  It's easy, unobtrusive, and offers only upside.  And not only will you excise spelling mistakes from your code -- you'll also prevent that annoying kid in the front of the class from bothering you about stuff you don't have time for.

Learn more about GhostDoc's truly source code spell checker and eliminate embarrassing typos in your apps and documentation before you ship them.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Wednesday, 14 September 2016 07:06:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 18 August 2016

Notwithstanding some oddball calculator and hobby PC hacking, my first serious programming experience came in college.  A course called "Intro to C++" got us acquainted with arrays, loops, data structures and the like.  Given its introductory nature, this class did not pose a particularly serious challenge (that would come later).  So, with all of the maturity generally possessed by 18 year olds, we had a bit of fun.

I recall contests to see how much application logic we could jam into the loop conditions, and contests to see how much code could be packed onto one line.  These sorts of scavenger hunt activities obviously produced dense, illegible code.  But then, that was kind of the point.

Beyond these silly hijinks, however, a culture of code illegibility permeated this (and, I would learn later) other campuses.  Professors nominally encouraged code readability.  After all, such comments facilitated partial credit in the event of a half-baked homework submission.  But, even still, the mystique of the ingenious but inscrutable algorithm pervaded the culture both for students and faculty.  I had occasion to see code written by various professors, and I noticed no comments that I can recall.

Professionalism via Thoroughness

When I graduated from college, I carried this culture with me.  But not for long.  I took a job where I spent most of my days working on driver and kernel module programming.  There, I noticed that the grizzled veterans to whom I looked up meticulously documented their code.  Above each function sat a neat, orderly comment containing information about its purpose, parameters, return values, and modification history.

This, I realized, was how professionals conducted themselves.  I was hooked.  Fresh out of college, and looking to impress the world, I sought to distinguish myself from my undisciplined student ways.  This decision ushered in a period of many years in which I documented my code with near religious fervor.

My habit included, obviously, the method headers that I emulated.  But on top of that, I added class headers and regularly peppered my code with line comments that offered such wisdom as "increment the loop counter until the end of the array."  (Okay, probably not that bad, but you get the idea).  I also wrote lengthy readme documents for posterity and maintenance programmers alike.  My professionalism knew no bounds.

Clean Code as Plot Twist

Eventually, I moved on from that job, but carried my habits with me.  I wrote different code for different purposes in different domains, but stayed consistent in my commenting diligence.  This I wore as a badge of pride.

While I was growing in my career, I started to draw inspiration from the clean code movement.  I began to write unit tests, I practiced the SOLID principles, I watched Uncle Bob talks, made my methods small, and sought to convince others to do the same.  Through it all, I continued to write comments.

But then something disconcerting happened.  In the clean code circles I followed and aspired to, I started to see posts like this one.  In it, the author had written extensively about comments as a code smell.

Comments are a great example of something that seems like a Good Thing, but turn out to cause more harm than good.

For a while, I dismissed this heresy as an exception to the general right-thinking of the clean code movement.  I ignored it.  But it nagged at me nonetheless, and eventually, I had to confront it.

When I finally did, I realized that I had continued to double down on a practice simply because I had done it for so long.  In other words, the extensive commenting represented a ritual of diligence rather than something in which I genuinely saw value.

Down with Comments

Once the floodgates had opened, I did an about-face.  I completely stopped writing comments of any sort whatsoever, unless it was part of the standard of the group I was working with.

The clean coder rationale flooded over me and made sense.  Instead of writing inline comments, make the code self-documenting.  Instead of comments in general, write unit and acceptance tests that describe the desired behaviors.  If you need to explain in English what your code does, you have failed to explain with your code.

Probably most compelling of all, though, was the tendency that I'd noticed for comments to rot.  I cannot begin to estimate how many times I dutifully wrote comments about a method, only to return a year later and see that the method had been changed while the comments had not.  My once-helpful comments now lied to anyone reading them, making me look either negligent or like an idiot.  Comments represented duplication of knowledge, and duplication of knowledge did what it always does: gets out of sync.

My commenting days were over.

Best of All Worlds

That still holds true to this day.  I do not comment my code in the traditional sense.  Instead, I write copious amounts of unit, integration and acceptance tests to demonstrate intent.  And, where necessary and valuable, I generate documentation.

Let's not confuse documentation and commenting.  Commenting code targets maintenance programmers and team members as the intended audience.  Documenting, on the other hand, targets external consumers.  For instance, if I maintained a library at a large organization, and other teams used that library, they would be external consumers rather than team members.  In effect, they constitute customers.

If we think of API consumers as customers, then generating examples and documentation becomes critically important.  In a sense, this activity is the equivalent of designing an intuitive interface for end-users of a GUI application.  They need to understand how to quickly and effectively make the most of what you offer.

So if you're like me -- if you believe firmly in the tenets of the clean code movement -- understand that comments and documentation are not the same thing.  Also understand that documentation has real, business value and occupies an important role in what we do.  Documentation may take the form of actual help documents, files, or XML-doc style comments that appear in IntelliSense implementations.

To achieve the best of all worlds, avoid duplication.  Make publishing documentation and examples a part of your process and, better yet, automate these activities.  Your code will stay clean and maintainable and your API users will be well-informed and empowered to use your code.

Learn more about how GhostDoc can help simplify your XML Comments, produce and maintain quality help documentation.

About the Author

Erik Dietrich

I'm a passionate software developer and active blogger. Read about me at my site. View all posts by Erik Dietrich

posted on Thursday, 18 August 2016 07:45:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Monday, 18 July 2016

Version 5.2 of GhostDoc is a minor feature release for the v5.0 users includes:

  • Support for Visual Studio 2015 Update 3
  • Fixes for the latest ASP.NET Core projects
  • GhostDoc now treats underscore as a delimiter to improve summary generation for underscore delimited identifiers
  • "Use Modern URLs" Help Configuration option for declarative help documentation file naming - namespace-classname-membername.htm
  • Option to turn on/off Documentation Hints during setup
  • (Pro) (Ent)Comment Preview is now rendered using the FlatGray theme
  • Plenty of improvements and bug fixes

For the complete list of changes, please see What's New in GhostDoc v5

For overview of the v5.0 features, visit Overview of GhostDoc v5.0 Features

This version is a required update for Visual Studio 2015 Update 3 users.

Download the new build at http://submain.com/download/ghostdoc/

posted on Monday, 18 July 2016 18:07:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Friday, 05 February 2016

Version 5.1 of GhostDoc is a maintenance release for the v5.0 users; includes minor enhancements and number of important bug fixes. Many of the fixes are relevant to the Visual Studio 2015 environment, so while everyone will benefit from this update, it is highly recommended for the Visual Studio 2015 users.

For the complete list of changes, please see http://support.submain.com/kb/a42/whats-new-in-ghostdoc-v5.aspx

For overview of the v5.0 features, visit http://submain.com/blog/ReleasedGhostDocV50.aspx

posted on Friday, 05 February 2016 19:33:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Monday, 23 November 2015
Note to GhostDoc Pro v4 users: The v4 licenses won’t work with the v5. We have sent out the v5 license codes to users with License Protection and active Software Assurance subscription. If you have not received or misplaced your new license, you can retrieve it on the My Account page. See more information at the bottom of this post.

Both Pro and Enterprise editions of GhostDoc in version 5 introduce Documentation Quality hints in Visual Studio editor; Documentation Management assistance - find auto-generated comments, edit or remove the bulk created docs; identify and fix comments that are missing, out of sync or can be copied from base class; mark generated XML comments as auto-generated and "to be edited". The v5 also includes multiple Help documentation themes and layouts to choose from.

The free version of GhostDoc has been re-branded as GhostDoc Community Edition and adds general improvements, limited generation of CHM help documentation as well as the means to find auto-generated comments.

GD_v5_new_commands

The new menu commands

  • Documentation Quality Hints in Visual Studio editor
  • Documentation Maintenance - Find auto-generated comments - edit or remove the bulk created docs
  • Documentation Maintenance - Identify and fix comments that are missing, out of sync or can be copied from base class
  • Theme support for generated help documentation and new themes - Flat Gray and Flat Main
  • Official Visual Studio 2015 support
  • Options to add Auto-generated doc and TODO 'Edit' attributes
  • Option to have the default summary text focused and selected when using Document This command - allows to edit/override the summary quickly
  • Exclude from Documentation action – marks a member with a tag to exclude it from the help documentation
  • Hide/Show Comments feature – an easy way to expand/collapse documentation comments to minimize the XML Comments footprint in the Visual Studio code editor
  • New Summary Override table in Options - configure predefined summaries for specific member or type names instead of auto-generated
  • A basic Build Documentation feature is now available in the Community Edition of GhostDoc – while quite limited and watermarked, yet allows to produce simple CHM help documentation for personal use without paying for the commercial version

For the detailed list of v5.0 changes see What’s New in GhostDoc v5.

To see new features by product edition see this page - http://submain.com/ghostdoc/editions/


Documentation Quality Hints

This new feature provides real-time visual hints in the Visual Studio Editor window to highlight members which have documentation issues that require attention.

GD_v5_maint_hints

The following documentation hint actions included with this release make it very easy to maintain the documentation quality:

GD_v5_maint_hints_list


Documentation Maintenance

This feature will help you identify missing documentation, find auto-generated XML comments, maintain your documentation, and keep it up to date. Once these are found, GhostDoc provides the tools to edit or remove the bulk created docs, add missing or fix the dated documentation – one by one or as a batch. You can fine tune the search criteria and use your own template library if yours is different from the built-in.

  • Find auto-generated docs and edit or remove them
  • Find and fix members that are missing documentation
  • Discover members that have parameters, return types, and type parameters out of sync with the existing XML comments and fix the comments
  • Find members that can have XML docs copied from the base class
  • Find documentation that require editing

GD_v5_maint_autogen

The Community Edition only allows to find auto-generated documentation and not batch actions – only one action at a time.


Help Documentation Themes

In the v5 we are introducing theme support for the generated help documentation and including two new themes, The old help doc view preserved as the Classic theme. You can see the new theme preview here - Flat Gray (default) and Flat Main.

The Enterprise Edition users can modify the existing themes or create and deploy own help documentation themes – now easier than ever!

The Community Edition theme selection is limited to one – Classic.

GD_v5_help_sample


Auto-generated doc and TODO 'Edit' attributes

The option to add tag to XML comment is intended to provide an explicit flag that the comment has been generated automatically.

The option to add a TODO comment “TODO Edit XML Comment Template for {member name}” which in turn adds a TODO task into the Visual Studio Task List –> Comments as a reminder for the auto-generated comment requires editing.

GD_v5_autogen_todo

Both flags can be used as additional criteria for the documentation quality hints and documentation management “Find auto-generated Documentation” feature. When generating help documentation these flags are also accounted for – the flagged members can be included, ignored or highlighted in the final docs.


Summary Override

The Summary Override table allows to configure predefined summaries for specific member or type names to be used instead of the auto-generated. We ship some predefined summary overrides and you are welcome to add your own. If you find a summary override that the GhostDoc user community can benefit of, please submit it to us to be reviewed for the inclusion.

GD_v5_summary_override

 

How do I try it?

Download the v5.0 at http://submain.com/download/ghostdoc/


Feedback is what keeps us going!

Let us know what you think of the new version here - http://submain.com/support/feedback/


Note to the GhostDoc Pro v4 users
: The v4.x license codes won't work with the v5.0. For users with License Protection and active Software Assurance subscription we have sent out the v5.x license codes. If you have not received or misplaced your new license, you can retrieve it on the My Account page. Users without the License Protection or with expired Software Assurance subscription will need to purchase the new version - currently we are not offering upgrade path other than the Software Assurance subscription. For information about the upgrade protection see our Software Assurance and Support - Renewal / Reinstatement Terms

posted on Monday, 23 November 2015 20:02:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 04 December 2014

First, we want to thank all of you for the support and loyalty you have given us over the last few years. We truly have the most amazing and passionate community of developers on the planet, and it makes our job an absolute joy. If you already have a GhostDoc Pro with License Protection, rejoice! The upcoming changes are not going to affect you (and if you were thinking about purchasing additional licenses, now is the time).

If you don't have GhostDoc Pro, this is your last chance to purchase it with the License Protection and receive free upgrades for the life of the product.

We are working harder than ever to bring more great features to your favorite plugin. We are super excited about the things we're working on and can't wait to share them with you over the next few months!

We will be making upgrade protection changes for new GhostDoc Pro users in order to align GhostDoc Pro maintenance with all other SubMain's products.

Starting January 1, 2015, for new license purchases only we are retiring the lifetime License Protection option for GhostDoc Pro and replacing it with annual Software Assurance subscription offering.

If you have been thinking buying new license(s) or adding more licenses, now is the time! Purchase GhostDoc Pro with License Protection by December 31, 2014 and save big on future GhostDoc Pro upgrades!

Purchase GhostDoc Pro w/ License Protection now

What is Software Assurance subscription?

SubMain customers can purchase 12 months of Software Assurance subscription with the purchase of any new license. Upgrade protection includes access to all major and minor version upgrades for 12 months from the date of purchase at no additional charge.

Upgrade Protection Timeline 2015

For example, if a new GhostDoc Pro license is purchased on May 1, 2015, upgrade protection will expire on April 30, 2016. During this time, the customer can download and install any minor version upgrades. In addition, if SubMain issues a major release of GhostDoc Pro during the subscription period, the license can be upgraded to the latest version at no additional charge. With SubMain's Software Assurance, customers will always have access to the latest features and fixes.

For more information please see Software Assurance - Renewal / Reinstatement

Again, please note that this new upgrade protection subscription will only affect new license purchases after January 1, 2015. All existing customer licenses with License Protection and those purchased by December 31st, 2014 will be honored and free upgrades will be provided to users with License Protection for the life of the product.

Thanks again for all of your support. Keep an eye out for more new exciting releases coming very soon!

[Edit: added some frequently asked questions]

Q: How does the Software Assurance subscription work for GhostDoc Pro?

A: It works the same way it does for all other SubMain products - the initial subscription term is one year from the purchase date. It is renewed at the end of the subscription for another year unless you choose to discontinue the subscription. If your license purchase has not included subscription auto-renewal, you need to renew your subscription manually in order to keep it current.

For more information please see Software Assurance - Renewal / Reinstatement

Q: I have purchased GhostDoc Pro without the License Protection. Can I add it now?

A: No, License Protection is not something that can be added after the license purchase.

Q: How long do I get updates if I don't purchase Software Assurance subscription?

A: With a new license purchase you get 90 days of free product updates if you have not purchased the Software Assurance subscription option.

Q: With License Protection do I get all future features or not?

A: Customers who purchased GhostDoc Pro with License Protection before it is replaced with the Software Assurance subscription get exactly the same features as the users with subscription. Think of the soon to be retired License Protection as a prepaid lifetime subscription.

posted on Thursday, 04 December 2014 11:40:31 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Tuesday, 27 May 2014

GhostDoc v4.9 Update 1 adds support for Shared Projects in all editions and introduces command line version in the Enterprise Edition:

  • (Ent) New feature - command line version - enables generating help documentation during build process for a specific Help Configuration
  • Added support for Visual Studio 2013 Update 2 Shared Projects/Universal Apps
  • Improvements and bug fixes

For detailed list of changes and fixes please see What's New in GhostDoc v4.x

How do I try it?

Download v4.9 at http://submain.com/download/ghostdoc/

posted on Tuesday, 27 May 2014 12:56:01 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Wednesday, 05 March 2014

GhostDoc v4.9 is mainly a stability release but it also introduces new Enterprise edition feature:

  • (Ent) New feature - ability to add custom pages to produced help documentation in GhostDoc Enterprise via Conceptual Content concept
  • Improvements and bug fixes

For detailed list of changes and fixes please see What's New in GhostDoc v4.x

How do I try it?

Download v4.9 at http://submain.com/download/ghostdoc/

posted on Wednesday, 05 March 2014 19:19:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Tuesday, 12 November 2013

As an active member of the Microsoft Visual Studio Industry Partner (VSIP) program, we again are proud to be VS2013 sim-ship partner and shipping all editions of GhostDoc v4.8 today simultaneously with the release of Visual Studio 2013.

This release includes official and complete support for Visual Studio 2013 as well as number of improvements and fixes. For details please see What's New in GhostDoc v4.8

How do I try it?

Download v4.8 at http://submain.com/download/ghostdoc/

posted on Tuesday, 12 November 2013 00:15:31 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 15 August 2013

We are happy to introduce the release of GhostDoc v4.7, a version that is greatly influenced by feedback from our users. It extends Visual Studio 2013 support and introduces an Enterprise version, Help Configurations, Help Content Targeting, embedding images into help markup, hyperlinking to base .NET Framework classes, abbreviation expansion, Non-breaking Words list, and much more:

  • Visual Studio 2013 support
  • Introduced GhostDoc Enterprise
  • (Pro) New Help Configuration feature - save custom configured help generation settings and switch between them easily
  • (Pro) Help Content Targeting - ability to create a (partial) 'filtered' help file based on attributes by using <tags/> in XML Comment and tag filtering in Help Configuration. If you need to have different help content for public API users, testers, internal documentation, etc, you can do that now!
  • New Abbreviations dictionary enables expanding abbreviations to full words (for example, 'args' -> 'arguments')
  • New Non-breaking Words list to preserve splitting when comment template is generated (for example, 'CheckBox' or 'ListView')
  • (Pro) Embed/reference images into the Help markup
  • (Pro) Option to skip documenting private/internal/protected members with Document File/Type batch commands
  • (Pro) .NET Framework classes are now hyperlinked to corresponding Microsoft reference page for additional information
  • (Ent) Customize Comment Preview
  • (Ent) Customize help layout and template

For the complete list of v4.7 changes see What's New in GhostDoc and GhostDoc Pro v4.7

GhostDoc Enterprise

We have identified a clear need for a new kind of GhostDoc product, specifically suitable for enterprises and customers who need advanced configuration features for the help file output.

The GhostDoc Enterprise version that we are officially introducing today offers silent deployment options, full customization of the template and layout of the Comment Preview and Help Files. The Enterprise license customers are also eligible for the on-premises Enterprise Licensing Server option.

For edition comparison please see this page - http://submain.com/ghostdoc/editions/

HelpConfiguration

Help Configuration and Help Content Targeting

The new Help Configuration feature enables you to create ready-to-use help generation profiles. You can easily switch between profiles, depending on what kind of help you are producing. Also you can define attributes with <tags /> in XML Comment and use tag filtering in Help Configuration to target Help content to your specific audience.

Help Configuration profiles include settings for:

  • Output format
  • Scope
  • Projects to include
  • Header and footer
  • New tag filtering for help content targeting

How do I try it?

Download v4.7 at http://submain.com/download/ghostdoc/

Feedback is what empowers us!

Let us know what you think of the new version here - http://submain.com/support/feedback/

posted on Thursday, 15 August 2013 07:12:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 17 January 2013

The .5 release of GhostDoc builds up on the version 4.0 features offering more flexibility for spell checking and help file generation. Most significant changes in v4.5 are:

  • (Pro) New Template Libraries feature with Export/Import
  • (Pro) New output formats for generated Help files
    • Html Help1 (.CHM)
    • MS Help 2 (.HxS)
    • MS Help Viewer aka MS Help 3 (.MSHC)
    • Website (HTML, ASP.NET, PHP)
  • (Pro) Options Dialog: solution specific settings for Ignore lists, Solution Dictionary and Help File, User Dictionary
  • (Pro) Added Spelling suggestions window to replace SmartTag. The older SmartTag option can be turned back on in the Options
  • (Pro) Custom tag support in Preview Comments and Build Help File
  • (Pro) AllMembers, Methods, Properties, Events, Fields, Operators sections to the generated Help file
  • Combined arguments of the same exception type into tag text
  • Help file/Preview now renders correct project language
  • Added syntax highlighting of the blocks in Help File/Preview
  • Added "Send Feedback..." to enable easy way of providing feedback right from the product menu

For complete list of v4.5 changes see What's New in GhostDoc and GhostDoc Pro v4.5

gd45_TemplateLibrary

Template Libraries

While GhostDoc Pro T4 template mechanism provides maximum flexibility how you can tweak and reconfigure your XML Comments and even regular comments, until now there was no easy way to share the set of templates with your team or the community.

Today we are introducing Template Libraries - you can Export the whole set of your custom templates and distribute it as one file which can be imported. Template Library includes meta-data - the library author, company name and contact information. To access the feature use Options -> Rules -> Export.

We will be hosting a section on our web site where we publish GhostDoc Pro Template Libraries we release. If you have specific comment formats you want us to release, send your requests in.

We also want to encourage sharing your templates with the community. Contact us if you have template library you was us to publish.

gd45_HelpFormats

New Help File Formats and Options

When we introduced a simple single click way of generating help file from your project XML comments, we realized that just one CHM format is not enough and we would need to add options to tweak your help file output.

Today GhostDoc Pro can build into the following help file formats:

  • Html Help1 (.CHM)
  • MS Help 2 (.HxS)
  • MS Help Viewer aka MS Help 3 (.MSHC)
  • Website (HTML, ASP.NET, PHP)

You also have the following options when building help file with GhostDoc Pro:

  • Select solution projects that you want to be included into the help file
  • Define Header and Footer for the help file pages
  • Decide whether you want to include Private, Internal, Protected members

How do I try it?

Download v4.5 at http://submain.com/download/ghostdoc/

posted on Thursday, 17 January 2013 18:45:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Wednesday, 12 September 2012

Note to GhostDoc Pro v3 users: Your v3 license won’t work with v4. We will be sending new license codes shortly to those of you with License Protection.

We are happy to announce the release of GhostDoc v4 and GhostDoc Pro v4 aligned with Visual Studio 2012 release as part of our VS2012 sim-ship commitment!

Version 4 is a major milestone for us with great new features and rewrites that we have done over the last year. Here are the most significant additions to the GhostDoc feature set:

  • Visual Studio 2012 support
  • (Pro) Source code Spell Checker
  • C/C++ language support
  • XML Comment Preview
  • (Pro) Build Help File
  • StyleCop Compliance – comments generated by GhostDoc are now pass StyleCop validation
  • Exception Documentation - exceptions raised within a method are documented in the XML Comment
  • (Pro) File Header menu and template
  • (Pro) Visual Studio toolbar with commands for documenting, comment preview and spell-checking
  • (Pro) Options -> Global Properties - allows to reference custom configured user properties within T4 templates (CodeIt.Right users will find this very familiar)
  • (Pro) IntelliSense in the T4 template editor
  • Version update notification – you won’t miss new version release ever again!

For detailed list of v4 changes see What's New in GhostDoc and GhostDoc Pro v4.0

Spell Checker

GDv4_SpellChecker_thumb5GhostDoc Pro Spell Checker features:

  • Check Spelling as you type
  • Spell Checking for XML Comments
  • Spell Checking for code elements
  • Spell Checking for strings and comments
  • Spelling SmartTag in the VS Code Editor
  • Added support for OpenOffice dictionaries and multiple languages
  • Ignore files and file extensions
  • Custom User Dictionary
  • Custom Dictionary by Solution
  • Solution wide Spelling Report
  • Check Spelling for
    • Active Document
    • Selected Documents
    • Current Project
    • Entire Solution

Comment Preview

Do you want to see how your XML Comment will look like in the help file? Have HTML tags encoded in the XML Comment and want to make sure your HTML is correct? GhostDoc Comment Preview is here to help!

GDv4_CommentPreview_thumb2

How do I try it?

Download v4 at http://submain.com/download/ghostdoc/

Note to Beta testers: We appreciate your contribution to this release and we will be contacting shortly those of you who provided feedback during the alpha/beta testing program.

Note to GhostDoc Pro v3 users: We have changed licensing schema in v4.0 and your v3.x license codes won't work with v4.0. For users with License Protection we will be sending v4.x license codes shortly. Users without the License Protection have to purchase new version - currently we are not offering upgrade path other than the License Protection program.

posted on Wednesday, 12 September 2012 16:00:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Wednesday, 20 June 2012

Note to GhostDoc Pro v3 users: Please use the temporary license above, your v3 license won’t work with v4. Once v4 is released we will be sending new license codes to those of you with License Protection.

After a round of private Alpha/Beta for GhostDoc we are excited to release Beta 2 of GhostDoc and GhostDoc Pro and make it available as part of the public Beta program!

Version 4 is a major milestone for us with great new features and rewrites that we have done over the last year. Here are the most significant additions to the GhostDoc feature set:

  • Visual Studio 2012 support
  • (Pro) Source code Spell Checker
  • C/C++ language support
  • XML Comment Preview
  • StyleCop Compliance – comments generated by GhostDoc are now pass StyleCop validation
  • Exception Documentation - exceptions raised within a method are documented in the XML Comment
  • (Pro) File Header menu and template
  • (Pro) Visual Studio toolbar with commands for documenting, comment preview and spell-checking
  • (Pro) Options -> Global Properties - allows to reference custom configured user properties within T4 templates (CodeIt.Right users will find this very familiar)
  • (Pro) IntelliSense in the T4 template editor
  • Version update notification – you won’t miss new version release ever again!

For detailed list of v4 changes see What's New in GhostDoc and GhostDoc Pro v4.0

Spell Checker

GDv4_SpellCheckerGhostDoc Pro Spell Checker features:

  • Check Spelling as you type
  • Spell Checking for XML Comments
  • Spell Checking for code elements
  • Spell Checking for strings and comments
  • Spelling SmartTag in the VS Code Editor
  • Added support for OpenOffice dictionaries and multiple languages
  • Ignore files and file extensions
  • Custom User Dictionary
  • Custom Dictionary by Solution
  • Solution wide Spelling Report
  • Check Spelling for
    • Active Document
    • Selected Documents
    • Current Project
    • Entire Solution

Comment Preview

Do you want to see how your XML Comment will look like in the help file? Have HTML tags encoded in the XML Comment and want to make sure your HTML is correct? GhostDoc Comment Preview is here to help!

GDv4_CommentPreview

How do I try it?

Download the BETA at http://submain.com/download/ghostdoc/beta/

What’s in it for me?

We will be rewarding GhostDoc Pro licenses (as we always do) at the end of the private/public beta program to those who provide feedback.

Where do I post feedback?

Please post your v4 Beta feedback in the GhostDoc Beta forum

What about GhostDoc Pro license?

The Pro trial license will allow you to run it for 14 days. To get past that point, please use the license below:

063A0-29A49-A6083-692D1-32CFC      <- good through 09/01/2012

19E95-459BB-E531B-288C0-08659        <- good through 10/01/2012

Note to GhostDoc Pro v3 users: Please use the temporary license above, your v3 license won’t work with v4. Once v4 is released we will be sending new license codes to those of you with License Protection.

posted on Wednesday, 20 June 2012 22:16:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 05 April 2012

We posted earlier that on 2/29 when Microsoft announced the Visual Studio 11 Beta, SubMain was one of the first partners with CodeIt.Right product that provided full support for the new VS Beta. We currently are running private Beta program for our GhostDoc product that is also VS11 Beta compatible.

We are happy to announce that SubMain is one of the partners to sim-ship (Simultaneously Ship) our products together with the Visual Studio 11 RTM! You will be able to enjoy fully compatible version of our products when you install Visual Studio 11 on the release day!

In the meantime you are welcome to test drive CodeIt.Right and GhostDoc together with Visual Studio 11 Beta:

Get-VS-11-Beta

posted on Thursday, 05 April 2012 06:49:00 (Pacific Standard Time, UTC-08:00)    #    Comments [2]   
 Wednesday, 24 August 2011

PrettyCode.Print and StudioTools no longer fit our strategic corporate direction to deliver best code quality tools on the market. 

Discontinuing these products enables us to reinvest the efforts into our flagship products and offer even better code quality tools. We will be releasing new greatly enhanced versions of our existing products as well as new products over the next six months. For a sneak peek of what’s coming please see our Product Feedback board.

PrettyCode.Print
PrettyCode.Print for VB6/VBA and PrettyCode.Print for .NET will no longer be further developed. Both products will be converted into a free download in their current state. While we will continue to offer technical support for PrettyCode.Print products for six more month from now, there will be no enhancements, improvements nor bug fixes for these two products.  You can download PrettyCode.Print for VB6/VBA and PrettyCode.Print for .NET in the Community Downloads section.

CodeIt.Once
CodeIt.Once is retired and no longer available for download. We encourage you to learn about our CodeIt.Right product which offers automated refactorings and proactively finds the opportunities for refactoring and improving your code.

StudioTools
StudioTools is retired and will no longer be offered for download or supported.

CodeSpell
CodeSpell will not be available for purchase for approximately 6 months. The CodeSpell engine is being rewritten to allow greater flexibility and better features, after which, the code spelling feature will be offered as part of our GhostDoc Pro product. All customers that purchased CodeSpell from SubMain (after March 9th, 2010) will be offered, at no charge, the equivalent number of licenses for GhostDoc Pro once the code spelling feature is released.

We sincerely appreciate your continued support and look forward to working with you in the future.

posted on Wednesday, 24 August 2011 22:47:26 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Friday, 10 December 2010
Holiday Offer

SubMain is proud to spread the holiday cheer by offering customers best savings of the year with free 1 year of Software Assurance and Support, free lifetime License Protection and great savings on multiple license purchases.

Get Software Assurance and Support absolutely free!

From now until January 7, purchase any new CodeIt.Right licenses and receive 1 year of Software Assurance and Support subscription at no additional cost. Normally priced at $100 per user ($150 per user for Enterprise Edition), Software Assurance annual subscription plan is the most cost effective and convenient way to stay current with the latest versions of our products and get priority support when you need it.

Plus free License Protection!

If you purchase just released GhostDoc Pro, you will receive free License Protection and secure GhostDoc Pro updates and new versions at no charge for the product lifetime.

GhostDoc Pro Edition is enhanced version of the product that gives users complete control over your XML Comment content and layout as well as automates XML Comment generation via batch actions.

Get it today! No hurdles! No hoops!

It is easy to get your free software assurance subscription and license protection. Just place your order on the SubMain website by January 7, and we will automatically give you the free year of software assurance and support subscription. If your purchase includes GhostDoc, you will automatically receive lifetime license protection for free too. No hassle. No headaches.

But wait, there is more!

On the top of the free offers above, you can save even more when you buy multiple CodeIt.Right licenses:

  • Save 20% on CodeIt.Right Standard Edition 5 license pack

  • Save 30% on CodeIt.Right Enterprise Edition 10 license pack

Email us at sales@submain.com for information on the the 5 and 10 pack discounts.

Need more info about SubMain products?

Learn more about SubMain products

Ready to get your holiday bonus?

Buy now for the holiday offer

Still have questions?

No problem! Contact the SubMain sales department via email sales@submain.com

 

posted on Friday, 10 December 2010 01:15:02 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Thursday, 09 December 2010

Today we are announcing the release of GhostDoc v3.0 - a new major release of the product. This version includes product usability and menu changes, adds many new features - menus, configuration rules, configuration options. It also features new error logging to improve troubleshooting of GhostDoc issues. The new version introduces GhostDoc Pro Edition - enhanced version of the product that gives users complete control over your XML Comment content and layout as well as automates XML Comment generation via batch actions.

For Edition comparison please see GhostDoc product page - http://submain.com/ghostdoc/

GhostDoc Pro

New in v3.0:

  • (Pro Only) New Document Type feature - generates XML comments for the entire type/class
  • (Pro Only) New Document File feature - generates XML comments for the entire file
  • (Pro Only) Introduced T4 template based rules that replace rule macros of the Free version
  • Improved support for VS2010
  • New Load/Unload menu items allow to disable GhostDoc temporary without uninstalling it
  • New Help menu item
  • New option to and menu to Re-assign Shortcut
  • Added Rule for read-only property to turn off generation of the tag line
  • Added Rule for private constructor
  • Added support for new tags - <inheritdoc>, <author> and <remarks>
  • Added support for enums, delegates and fields
  • Added option to modify Configuration Folder path
  • Added option to Keep Single Line when for long comments
  • Changed leading tabs to leading spaces for compatibility with other products
  • Changed "gets or sets" summary prefix to just "Gets" when setter is private
  • Fixed automatically implemented properties issue

GhostDoc and GhostDoc Pro build 3.0.10340 are available for download right now at http://submain.com/download/ghostdoc/

Please note GhostDoc EULA was updated to reflect the introduction of GhostDoc Pro.

posted on Thursday, 09 December 2010 12:55:34 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Tuesday, 23 February 2010
Roadmap_426x282

Code Quality developer tools is the direction we've been following since the introduction of CodeIt.Right and we are taking this commitment to the next level in 2010 with two new products and new features for our existing products.  One of the new products to be released in 2010 will assist in unit testing, code coverage and test code profiling; the second new product will be complementary to CodeIt.Right.  All three products together will comprise our new Code Quality Suite.  Additionally, we will continue to keep up with the Visual Studio 2010 release schedule and have all of our products 2010 compatible when VS2010 is RTM.

Here is what we are planning for 2010:

  • New product!

    • Coming March 2010:  we are adding to our product line by offering a unit test runner and code coverage product.

  • New product!

    • Project Anelare (code name) - we will provide details on this project as we get closer to a public preview.  At this point we can share that this will be product complementary to CodeIt.Right - together they will encompass our code quality package.

  • VS2010 support

    • For all products - most of our products are compatible with VS2010 RC, and we will be VS2010 RTM compatible by the time it RTMs.

  • CodeIt.Right

    • Optimized rule library performance:  the new version will be released the first week in March!

    • Community Rule Valuation & Review: we are pioneering "social" in code analysis by enabling the community to rate rules and provide feedback; as well as leverage the community feedback, best uses and best practices for each rule.

    • NEW Rules - with emphasis on security, FxCop/StyleCop parity, SharePoint, WPF & Silverlight rules.

    • (EE) Trend Analysis: monitor code quality improvements over time.

    • (EE) Integration with manual code review tools.

    • Global Suppressions:  adding support for GlobalSuppressions and extending syntax of the SuppressMessage attribute for more flexible in-code exclusions.

    • Multi-select in the violations list.

    • Copy Rule feature:  clone and change rule instance configuration

    • Command line enhancements: open command line/build violations output in Visual Studio for correction

    • Annotation: for excludes and corrections

    • XAML support:  enables building Silverlight and WPF specific rules

    • Profile Wizard:  quick start no-brainer user/project profile based on the project type, importance, community valuation, favorite food, etc

  • GhostDoc

    • We are currently prioritizing the feature set for the new version of GhostDoc. If you have a feature request that you have not submitted yet, share them with us in the GhostDoc forum.

Stay tuned to our blog for more details about our progress!

posted on Tuesday, 23 February 2010 09:13:00 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 Monday, 01 June 2009

As announced earlier today we just closed the acquisition of the popular XML Comment helper tool GhostDoc. We, SubMain, will continue to evolve the tool and distribute it as a free product.

We are also announcing today the availability of the new version of GhostDoc v2.5.09150 which improves the user setup experience, adds support for Visual Studio 2010 Beta 1 and full support for Visual Basic.

Additionally, today we are making available a new version of CodeIt.Right (v1.6.09151) that adds the IntelliComment feature based on the GhostDoc algorithm and offers improved and automated generation of XML Comments.

We are very excited about taking over the future of an excellent tool such as GhostDoc! We are committed to maintaining this wonderful free tool and we welcome the community feedback and suggestions.

For more on the agreement, please see the press release and interview with Serge Baranovsky and Roland Weigelt - What's in the shop for GhostDoc?

New in GhostDoc v2.5:
  • Compatible with VS2010
  • Support for VB - GhostDoc now has full support for VB
    • Removed "Enable experimental support for VB" option in Settings.
  • Improved product setup experience
    • Single setup for all supported versions of Visual Studio - VS2005, VS2008 and VS2010.
    • Setup will detect older version installed and automatically uninstall it.
  • Converted from VS Add-In to VS Package
  • Resolved installation issues related to the VS Add-In model - by converting to VS Package
Download

Download GhostDoc v2.5.09150 here - http://submain.com/download/ghostdoc 

Download CodeIt.Right v1.6.09151 here - http://submain.com/download/codeit.right 

posted on Monday, 01 June 2009 14:25:56 (Pacific Standard Time, UTC-08:00)    #    Comments [0]   
 

 
     
 
Home |  Products |  Services |  Download |  Purchase |  Support |  Community |  About Us |