How much code documentation in your .NET source is too much? Some background: I inherited a large codebase that I've talked about in some of the other questions I've posted here on SO. One of the "features" of this codebase is a God Class, a single static class with >3000 lines of code encompassing several dozen static methods. It's eve...
I'm quite familiar with PHP dockblocks since it's been my job for the last 15+ years. /** * Description * * @tag bla bla * @tag more bla bla */ What I'm trying to understand is if there is a standard like that for Delphi and/or FreePascal. From my analysis on an awful lot of code I never seen any, but I could be dead wrong....
I use NDoc 1.3.1 to generate documentation in VS .NET 2003, framework v1.1. For the following block /// <example> /// <code lang="C#" escaped="true"> /// try /// { /// // ... /// } /// catch (Exception ex) /// { /// // ... /// } /// </code> /// </example> in the code file, NDoc produces the contents in the <code> block formatte...
I was able to find a page from Safari Books Online that provides a template, but having never written POD comments, I'm not sure how good it is or if it is missing anything that might be considered convention to include. What are the conventions to follow when writing POD comments for Perl scripts? Is there anything like Sun's Javadoc C...
hi, we are using the java 6 scripting engine in our product, and now we are thinking on adding some debugging abilities. my question is: is it possible? does the java 6 scripting engine has the same capabilities like rhino as far as debugging. some documentation about how to start doing it, some code samples any information would be...
Hello, We are managing a C++/C# library and we noticed that many classes and functions were left undocumented. We thought about writing a script which would parse the code to look for undocumented classes and method to produce a list of undocumented classes/methods/functions. We would like, as well, the script to put the dOxygen tags ...
I'm new to PHP, and my current job requires me to pick up the language at an extremely quick pace. I'm a documentation stickler. I even like to write documentation. I'm familiar with accepted documentation syntax and tools for a handful of languages. This is not the case for PHP. I know there are always multiple methods for writing do...
For each class in the project SandCastle creates (among others) two pages: the main page, named T_class_full_name, with the description, Syntax, Inheritance Hierarchy and See Also and the members page, named AllMembers_T_class_full_name, with Constructors, Methods, Fields, etc. Is there a way to merge these two together - with the me...
How can I force Doxygen to show full include path? What do I mean: I have a class foo::bar::bee defined in bee.hpp in following directory structure: foo foo/bar foo/bar/bee.hpp Doxygen, when it documents foo::bar::bee class tells that you need to include <bee.hpp>, but for my software I need <foo/bar/bee.hpp> How can I cause Doxyge...
We deliver a number of assemblies to external customers, but not all of the public APIs are officially supported. For example, due to less than optimal design choices sometimes a type must be publicly exposed from an assembly for the rest of our code to work, but we don't want customers to use that type. One part of communicating the l...
Do you know about a tool to easily create documentation for both Javascript and PHP code? Something that takes comments in code similar to the one shown below: /********************************************************** This fucntion does something special... param1: ... param2: RETURNED VALUES: ... **********************************...
I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference. In general, what are some good guidelines when writing comments for a class and for a method? What should the NDoc comments say? What should they not say? I find ...
Hello, I still searched for this but without success. I would like to create 'Quick Help' entries in XCode for custom classes. Don't know Quick Help? Select a function-name, right-click and choose 'Quick Help' Then you can see function-description, etc. Somebody an idea how to accomplish this? Rene ...
We have developed an application in c# .net and aim to make it deployable within our intranet. We would like to have a solid documentation to go along with it but are unsure of the best platform to document this. Any tools available to facilitate this process? I found out about Doxygen, Htmlhelp or Dr Explain but i'm still not convinced...
For example: When I type Console.WriteLine and the intellisense pops up, the tooltip for that function reads only "void Console.WriteLine()". It no longer shows the summary of the function, "Writes the specified data, followed by the current line terminator, to the standard output stream." or what the values of the parameters should be....
Visual Studio has a nice feature to spit out a bunch of compiler warnings if some of the public members are missing XML documentation. I would love to have the same for internal, or better, any non-private members, but unfortunately so far I wasn't able to find how to configure the level of visibility for which to require XML documentat...