A GhostDoc Feature I Will Not Implement

I’ve received a number of requests for a new GhostDoc feature for documenting a whole source file at once. This feature is filed as item #45 in my issue tracking system, and its status is “rejected”.

The texts generated by GhostDoc are suggestions generated by some stupid code that breaks identifiers into separate words and juggles them around. Each and every text generated by GhostDoc has to be checked by the developer, and should be revised by the developer if necessary. Depending on your coding style, the time required for checking and revising the generated text usually is less than writing everything from scratch, i.e. using GhostDoc saves you time.

So that’s the idea: GhostDoc guesses some documentation text, you check the results, and in the end you’ve saved some time.

I’m pretty sure that many of us know at least one “motivationally challenged” developer who is very likely to skip the part where you actually have to use your own brain. If such a person has to document a class member by member, there’s at least a little chance that he/she will notice texts that are just too stupid (e.g. such classics like “Toes the string.” and “Ons the click”). But can you imagine the same person given the feature of running GhostDoc on a whole source file at once? DailyWTF, anyone?

6 Comments

  • Ronald,



    Since you won't do it, I am motivated to write a plugin to automate your plugin to comment the whole file, just to be able to see gems like “Toes the string.” on DailyWTF.



    In fact, if I were you, I'd open up a web page just collect these gems.

  • Hi Frank,



    > Since you won't do it, I am motivated to write a plugin to

    > automate your plugin to comment the whole file,



    I have no problem with that (because then I'm not the one to blame ;-)



    > In fact, if I were you, I'd open up a web page just collect these gems.



    That's a cool idea. I'll add a section to my GhostDoc website over the weekend.



    Roland

  • Where is the "Submit your own" link?

  • I thought the "Contact me" link at the top of the page would be sufficient... but ok, I'll add a link at a more prominent location.



    Roland

  • I understand the need for comments, but apparently, microsoft does not. What about for generated code from such nice tools like wsdl.exe and xsd.exe?

  • > What about for generated code from such nice tools like wsdl.exe and xsd.exe?

    For generated code (that gets replaced over and over again), you'd need a different tool. You wouldn't want GhostDoc to run over the complete file at once (producing a lot of nonsense in the worst case).
    Instead, the comments should be created and checked individually by the developer (as they are now). The comments then appear in the documentation XML file for the assembly (or some tool could create a separate file only for the generated source file, to reduce the danger of losing comments by merely recompiling). When the source file is generated again, these comments could be used by some tool to re-apply them to the new source file. Of course, there are some synchronisation issues (how to handle slight differences in method signature etc.), but maybe with some help by a GUI (letting the developer decide what to do) it should be possible to get to a solution that is good enough.
    Unfortunately, I don't have the time to write something like that, but maybe somebody else has.

Comments have been disabled for this content.