This is the archived version of Roland Weigelt's weblog that ran from 2003 to 2023 at weblogs.asp.net

Contents tagged with GhostDoc

  • Trying out What ChatGPT Knows About XML Doc Comments

    No Comments

    Back in 2003, I started a Visual Studio add-in called “GhostDoc” that used some simple heuristics to create basic XML doc comments as a starting point for writing the “real” documentation (remarks on the purpose, edge cases, special parameter values, etc. but not implementation or other internals). GhostDoc did not really understand the English language, but relied on recommended naming conventions of the .NET Framework. Later versions were also able to use documentation of base classes and interfaces.

    I worked on GhostDoc until 2009 when SubMain acquired the rights to the software. Since then, the topic of documentation continues to play an important role for me. Some of my hobby projects have a considerable amount of old code that has not been modified for years, and thus is used more like a third-party library. It is not uncommon that I come across a helpful <remark> tag that I added to the auto-generated XML doc comment for an “obvious” function  – wondering whether I would have written the remark back then if I had to write all the boiler text myself.

    Trying out ChatGPT

    When I got around to playing with ChatGPT, one thing I wondered whether it could write XML doc comments. So here is how that went:

    My question to ChatGPT:

    In the context of the .NET framework and the C# language, do you know what an XML doc comment is?

    ChatGPT’s answer:

    Yes, I'm familiar with XML doc comments in the context of .NET framework and C# language. XML doc comments are special comments that are used to document code elements such as classes, methods, properties, events, and parameters in C# code. They are written using XML syntax and provide a way to add documentation directly to the source code, which can be later extracted and used to generate documentation for the code.

    XML doc comments begin with three forward slashes (///) in C# and are placed immediately before the code element that is being documented. They can contain various XML tags such as <summary>, <param>, <returns>, <example>, etc., to provide structured documentation for the code element. For example, the <summary> tag can be used to provide a summary of what a code element does, the <param> tag can be used to document parameters of a method, and the <returns> tag can be used to document the return value of a method.

    XML doc comments are commonly used by developers to generate API documentation using tools such as Visual Studio's IntelliSense or third-party documentation generators like Sandcastle or DocFX. They can also be used to provide documentation for library users to understand how to use the code correctly and effectively.

    Question:

    Could you write an XML doc comment for a function with the following signature: public string GetDetailedExceptionMessage(Exception exception)

    ChatGPT:

    Sure! Here's an example of an XML doc comment for the given function signature:

    /// <summary>
    /// Gets a detailed exception message that includes the exception message, 
    /// inner exception message(s), and stack trace information.
    /// </summary>
    /// <param name="exception">The exception for which to retrieve the detailed message.</param>
    /// <returns>
    /// A string containing the detailed exception message, including the exception message, 
    /// inner exception message(s), and stack trace information.
    /// </returns>
    public string GetDetailedExceptionMessage(Exception exception)
    {
     // Implementation goes here
    }

    [… rest of answer omitted for brevity …]

    That is pretty impressive.

    And no, I do not have plans to write an XML doc generator using ChatGPT…

  • Zeit für Veränderungen

    5 Comments

    tl;dr: Ich ziehe mich aus der lokalen .NET Community (User Group Bonn-to-Code.Net, dotnet Cologne Community-Konferenz) zurück. Die gewonnene (Frei)zeit investiere ich, um in den nächsten Jahren ein umfangreiches Hobby-Projekt neu zu implementieren und dabei mit Hilfe der Universal Windows Platform bisher nicht umsetzbare Visionen zu realisieren.

    Eine Bestandsaufnahme

    Ich kann nicht gerade behaupten, dass mir in meiner Freizeit langweilig würde…

    Da sind zum einen meine Aktivitäten in der .NET Entwickler-Community:

    • 2006 gründete ich die Bonner .NET User Group “Bonn-to-Code.Net”, damit verbunden wurde ich Mitglied im Microsoft Community Leader/Insider Program, später TechConnect.
    • 2008 war ich zum ersten Mal an der Organisation einer Community-Konferenz beteiligt (AfterLaunch 2008)
    • 2009 organisierten Albert Weinert, Stefan Lange und ich die erste dotnet Cologne, später stieß mit Melanie Eibl ein weiterer wichtiger Baustein zum Team hinzu.

    Darüber hinaus spielt Basketball eine große Rolle in meinem Leben. Mittlerweile nicht mehr aktiv, sondern als Fan und Unterstützer des lokalen Basketball-Bundesligisten Telekom Baskets Bonn:

    • Von 1996 bis 2006 zunächst als Co-DJ (mit einer eigenen DJ-Software),
    • Ab 2006 betreute ich dann die Videowände in der Halle. Einerseits (man ahnt es schon) mit Software, andererseits mit Inhalten (Visual Design, Redaktion).
    • Mit der Installation von LED-Werbebanden 2013 wurde aus einer ehrenamtlichen Aufgabe schließlich eine bezahlte Nebentätigkeit mit einem gehörigen Teil “Bürokram” (Kommunikation mit Sponsoren, etc.).

    Zwischendrin veröffentliche ich auch gerne mal Software für Entwickler (GhostDoc 2003 – 2009, Emaroo ab 2010) und dieses Weblog gibt es auch bereits seit 2003.

    Bei allen diesen Aktivitäten geht es mir darum, etwas zu erschaffen, “etwas auf die Beine zu stellen”. Das bereitet mir viel Freude, bedeutet aber auch eine Menge Arbeit. Der zeitliche Spielraum ist mittlerweile sehr gering geworden und der Stresslevel, insbesondere wenn Basketball-Saison und dotnet Cologne-Vorbereitung parallel laufen, ist manchmal einen Tick zu hoch.

    Die Entscheidung

    Um in meiner Freizeit wieder mehr freie Zeit zu haben (die ich aber gleich wieder nutzen möchte, dazu gleich mehr) habe ich folgende Entscheidung getroffen:

    • Ich werde die Bonner .NET User Group “Bonn-to-Code.Net” nicht mehr weiterführen. Wie es mit der Bonner .NET Community weitergeht/weitergehen kann, dazu schreibe ich mehr auf den Kommunikationskanälen der User Group.
    • Damit erlischt auch meine Mitgliedschaft im Microsoft Community-Programm.
    • Ich werde mich aus der Organisation der dotnet Cologne zurückziehen, auch wenn es mir sehr schwerfällt. Man wird mich aber definitiv auf der dotnet Cologne 2018 finden können und hier und da werde auch ich Albert, Stefan und Melanie weiterhin unterstützen (z.B. mit der Software für die InfoScreens, mit der einen oder anderen Grafik in Adobe Illustrator oder wenn verhandlungssicheres Englisch gefragt ist).

    Der Plan

    Die Arbeit an der Software für die Videowände und LED-Werbebanden ist für jemanden wie mich, der ohnehin immer sehr am Visuellen interessiert war, einerseits sehr befriedigend, andererseits – bisher – aber auch immer ein wenig frustrierend. Die Vision, Darstellungen in “Fast-US-Sportfernsehen-Qualität” zu entwickeln (animierte Statistiken etc.), war für mich nie ganz zu erreichen. Denn die Windows Presentation Foundation (WPF) hat ihre Performance-Probleme architekturbedingt nie in den Griff bekommen, gleichzeitig kam ein tiefer Einstieg in DirectX wegen des (Zeit-)Aufwands nicht in Frage.

    Die Universal Windows Platform (UWP) sah von Anfang an sehr vielversprechend aus, weshalb ich im Sommer 2016 einen ersten Anlauf unternahm, mich darin einzuarbeiten – der im Herbst von der Basketball-Saison (Heimspiele in Bundesliga und europäischem Wettbewerb) und den Arbeiten für die dotnet Cologne jäh gestoppt wurde.

    In diesem Sommer habe ich dann angefangen, die WPF-basierte Software für die LED-Banden komplett neu unter UWP zu entwickeln. Mit ermutigenden Ergebnissen. Unter WPF bringt die Aufgabe, elf Videos (für elf Werbebanden) parallel abzuspielen und gleichzeitig die elf nächsten Videos vorzuladen, auch einen leistungsfähigen Rechner an seine Grenzen:

    • Die Videos ruckeln. Und das auf einem Rechner, der sonst umfangreiche 3D-Darstellungen flüssig in 2560x1600 Pixeln darstellt.
    • Das Abspielen ist von mysteriösen Stabilitätsproblemen im Dauerbetrieb geplagt (spontane Abstürze im Dauerbetrieb mal nach zwei, mal nach fünf Stunden). Eine Suche im Web zeigt: Ich bin nicht alleine.

    Hingegen läuft der Proof-of-Concept mit UWP superweich, einen Testlauf habe ich nach 20 Stunden selbst beendet.

    Mein Ziel ist nun, die Software bis zum Saisonbeginn “alltagstauglich” zu machen. Anschließend gehe ich daran, nach und nach auch die restliche, in den letzten zehn Jahren entstandene Software zu ersetzen. Damit dürfte ich einige Spielzeiten beschäftigt sein…

    Fazit

    Ich sehe in der Universal Windows Platform und ihren Fähigkeiten (Stichwort: Composition) eine riesengroße Chance, meine Visionen in der von mir gewünschten Qualität umzusetzen. Und der Ausblick auf die Zukunft auf der diesjährigen Microsoft Build-Konferenz, sprich Fluent-Design, war für mich ein einziges “oh ja, so etwas kann ich gebrauchen!”.

    Daher ist es jetzt für mich höchste Zeit, ernsthaft einzusteigen. Das heißt lernen, Erfahrungen sammeln, Zeit investieren – und deshalb klare Prioritäten zu setzen, auch wenn es vielleicht schwerfällt.

  • Welcome 2010

    1 Comment

    Things that have happened

    • I’m no longer responsible for maintaining GhostDoc, SubMain has taken over the development and this has freed up a considerable amount of time. Some of this time went into playing more computer games, a larger portion went into seriously digging into WPF.
       
    • The dotnet Cologne 2009, a community conference organized by the neighboring .NET user group Cologne and Bonn-to-Code.Net (which I founded exactly 4 years ago) became a huge success. In fact, almost too much of a success - we had to close registration a full month before the conference and the rooms sometimes were pretty crowded. There are plans for a dotnet Cologne 2010, but it’s too early to go into details.

    Things I have learned

    • The concept of “open space” / “unconference” can actually work. I attended the .NET Open Space 2009 in Leipzig and what I experienced blew away my initial skepticism. One thing to keep in mind is that this approach is not really a replacement for a conference in classic style – in my opinion the two styles supplement each other.
       
    • The more I learn about Silverlight and WPF, the more I start to see how much I don’t know yet. While the actual amount of concepts to learn is finite, knowing how to combine these to achieve a specific goal is something completely different.
       
    • Not much of a big surprise, just an observation: The lambda expressions introduced in C# 3.0 slowly but surely start to influence the way I think about/plan my code and (small scale) architecture.

    Things I’m looking forward to

    • Visual Studio 2010 when/if it’s released in good quality (please MS, take your time to get this release right, I still remember VS2005 before the SP!). I’m especially looking forward to the extensions for the editor that are now possible; when I saw the first samples, I was immediately reminded of one of my old blog posts back from 2003. Looks like we’re finally getting there!
       
    • Silverlight 4 and WPF 4: The basic concepts of WPF and Silverlight are promising, but at the same time there are still many quirks and missing pieces. It’s nice to see Microsoft is pushing hard to close the gaps, at the same time I still see a long way to go (enough work for version 5, 6 and 7). Performance is improving from version to version, but still can be a source of frustration. And I’m definitely looking forward to the day when Silverlight is a bit more specific about errors than just telling me AG_E_SOMETHING – but I guess I’ll have to wait for something after version 4 for that.

  • Upgrading from “Weigelt” GhostDoc to “SubMain” GhostDoc

    1 Comment

    As I wrote in an update to my “The Future of GhostDoc” blog post, the uninstaller of GhostDoc 2.1.3 contains a bug which (under specific circumstances) may lead to losing your Visual Studio settings – I’m really sorry about that.

    In the days after the first SubMain release in May (version 2.5.09150) I have helped the guys from SubMain in developing a working uninstaller for old GhostDoc versions, which is now included in the setup of the current GhostDoc version 2.5.09166 (published mid-June, though the website has been only updated recently).

    So the “right way” to upgrade from an old “Weigelt” GhostDoc version (up to 2.1.3) to a new “SubMain” GhostDoc version (starting with 2.5.09166) is:

    • DO NOT uninstall Weigelt GhostDoc
    • Just run the SubMain GhostDoc setup

    Everything else will be taken care of. Future updates (from one version of SubMain GhostDoc to another) also involve just running the installer of the new version.

  • The Future of GhostDoc

    4 Comments

    Today is the day that I'm finally able to speak about why things have been pretty quiet lately regarding the future of GhostDoc.

    I'm happy to announce GhostDoc has been acquired by SubMain, developer of tools like CodeIt.Right. The agreement covers the usage of GhostDoc's documentation generation technology in their products, as well as the availability of GhostDoc as a standalone product. SubMain will continue to maintain and distribute a non-crippled version of GhostDoc free of charge, and will make sure that it will work with future versions of Visual Studio like the upcoming VS2010. The first step is a new version 2.5 of GhostDoc that has been released just moments ago.

    For more information please take a look at a Q&A with Serge Baranovsky from SubMain and me that covers past, present and future of GhostDoc.

    As I already mentioned in the Q&A, from my experiences of working with the guys at SubMain (both on the legal and the technical stuff), I can say that GhostDoc is in good hands. The developers now have my issue tracking database where I collected and annotated all the feature requests of the recent years, but I also would like to ask every GhostDoc user to please let them know if you have ideas how to improve this tool.

    I'd like to use this opportunity to say a big Thank You to all GhostDoc users out their for their (overwhelmingly positive) feedback over the recent years. Thank You!
     

    Update: Important note for existing GhostDoc users
    There are uninstall issues with the old GhostDoc version 2.1.3 (and versions before) that under specific circumstances may lead to losing your Visual Studio settings on Vista machines. I'm already working on a solution to the problem (with help from one of the SubMain developers), in the meantime please back up your settings as described in this step-by-step guide before uninstalling the old GhostDoc version. During uninstallation, if a Visual Studio instance pops up and asks you to choose a developer profile, choose one and continue. This will lead to the loss of the settings, which then can be restored by importing the backup you just made before. Note that you have to choose a profile; cancelling the dialog will lead to a corrupted state of the uninstallation.

    The new GhostDoc from SubMain is using different install/uninstall/VS integration technology that has been proven in their other products and does not have such problems.

    Update 2: Please read this blog post on upgrading to GhostDoc 2.5 and later.

  • Spanish Configuration File for GhostDoc 2.1.3

    No Comments

    After an Italian configuration for GhostDoc there's now also a Spanish configuration available. As mentioned for the Italian version, I cannot comment on the quality. Also, please note that GhostDoc is intended for English documentation, which means that tweaking it for other languages is likely to run into problems sooner or later.

    On the other hand, a lot can be achieved with the help of some clever custom rules, so I recommend to try out the Spanish configuration. As usual, exporting the current configuration as a backup is definitely not a bad idea.

  • GhostDoc Tweaks

    No Comments

    When moving to a new development machine recently, I noticed that I was using a couple of (minor) customizations to GhostDoc on the old machine that are not included in the default configuration. Most of them were rather specific, but three custom rules that may be of general interest are for overrides of the methods ToString(), Equals() and GetHashCode(). Without the rules, the documentation is inherited from System.Object:

    /// <summary>
/// Returns a <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </summary>
/// <returns>
/// A <see cref="T:System.String"/> that represents the current <see cref="T:System.Object"/>.
/// </returns>
public override string ToString()

/// <summary>
/// Determines whether the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>.
/// </summary>
/// <param name="obj">The <see cref="T:System.Object"/> to compare with the current <see cref="T:System.Object"/>.</param>
/// <returns>
/// true if the specified <see cref="T:System.Object"/> is equal to the current <see cref="T:System.Object"/>; otherwise, false.
/// </returns>
/// <exception cref="T:System.NullReferenceException">The <paramref name="obj"/> parameter is null.</exception>
public override bool Equals( object obj )

/// <summary>
/// Serves as a hash function for a particular type.
/// </summary>
/// <returns>
/// A hash code for the current <see cref="T:System.Object"/>.
/// </returns>
public override int GetHashCode() 

    The comments are OK at first sight, but I don't really like the references to System.Object, I prefer "the current instance" instead. Fortunately, changing this in GhostDoc is pretty easy.

    In general, to replace the generated documentation for a specific method, property, etc., simply define a custom rule and make sure has a higher priority than the rule that would create the documentation otherwise (in the case of the above methods that would be the "inherited documentation" rule).

    The new rules are available as a configuration file you can download here (see the included ReadMe for instructions how to use it).

    Importing this file will not affect other parts of your configuration, but creating a backup of your current configuration is never a bad idea. After the import the rules will automatically have the highest priority, so no other steps are necessary.

  • Usage of GhostDoc in Large Corporations

    2 Comments

    A message to all developers in large corporations out there: If you try/have to approve the usage of GhostDoc because of company policy, you may get the response that legal problems prohibit the usage as no agreement could be reached with the author (i.e. me). To avoid the impression that I'm trying to rip off your company in any way, I'd like to explain this:

    If a company approaches me asking whether the usage of GhostDoc is allowed for commercial purposes, I point them to the license which clearly states that this is the case. If company policy still requires an explicit statement regarding commercial use, I don't have any problem with that, either.

    But: I will not sign any multi-page legalese for a piece of software that I didn't actively offer, let alone try to sell to a company in the first place. If my freeware license is not compatible with company policy, then that's unfortunate, but it's nothing I will do anything about - sorry.

  • Italian Configuration File for GhostDoc 2.1.3

    No Comments

    Even though GhostDoc is intended for English documentation (and there are no plans for future versions to change that), Luca Tagliaferri from Italy has created an Italian configuration file for GhostDoc 2.1.3. While I cannot comment on the quality (I haven't tried it, non parlo l'italiano), I recommend checking it out here. Just be sure to export your current configuration as a backup.

  • GhostDoc: A Look Back at 2007

    No Comments

    Here are some statistics for my Visual Studio add-in GhostDoc for the year 2007.

    Downloads for Visual Studio 2005

    • Version 1.9.5 (released back in 2006): 15294
    • Version 2.0.0 (released 2007–05–01): 11395
    • Version 2.1.0 (released 2007–06–24): 2351
    • Version 2.1.1 (released 2007–07–04): 24909
    • Version 2.1.2 (released 2007–11–25): 4873
    • Total: 58822

    Downloads for Visual Studio 2008

    • Version 2.0.0 (released 2007–05–01): 444
    • Version 2.1.0 (released 2007–06–24): 153
    • Version 2.1.1 (released 2007–07–04): 3202
    • Version 2.1.2 (released 2007–11–25): 3140
    • Total: 6939

    Downloads for Visual Studio .NET 2003

    • Version 1.3.0 (released back in 2005): 4409

    Donations by chosing an item from my Amazon WishLists (US, UK, DE):

    • Total: 7 (a huge Thank You to you guys and gals!)