Which tricks, hints or shortcuts do you use regularly when you document your sourcecode? What type of comment does help you most (or is most desired) when looking over a piece of sourcecode? For an example, we always use date, shortcut of name and a +, -, * (added, deletet/commented, modified) and then some description: // 30.04.09 PL...
I just joined a Heroic shop. The code appears to be clean and quality, but there is no documentation to speak of. (the code was written and maintained by a small group). Thus, new engineers need to reengineer from source to determine design. As the project is transitioning from a small (3) team to a larger team, I would like to docum...
Can anyone recommend guidelines for high-level documentation of Web services? This is the documentation that should allow someone with no knowledge about a particular Web service to come away with a basic understanding of its reason for being, its roadmap and examples of its usage. Such documentation should fit onto two printed sides o...
Just need it for a hand full of diagrams. Any recommendations? ...
My Situation: The data request chain of my application looks like this: (Client) -> (WebService) -> (SQL or OLAP Cube) The client is a Silverlight Application that uses a generated proxy to communicate with a WCF webservice. Which in turn does authorization and accesses SQL DB's and OLAP Cubes using a DAL component, basically it just...
Is there a generally-accepted documentation generator for Objective-C (similar to RDoc for Ruby)? I've seen Doxygen and ObjcDoc, and am wondering which is most widely used. ...
Hi there I come from writing PHP code, and there I was using PHPDoc standards, in order to write comments in the code. Now I'm trying to learn C/C++ (I'm using Visual Studio 2005), but I also wish to write good comments. Is any standard to use or/and a tool which will automatize the documentation construction later? many thx:) ...
I am wondering if there is a code documentor that can sync with a wiki. This would be useful for libraries where the end-users could edit better descriptions of function uses and examples. And any changes in the function signature could be automatically reflected on the wiki. Please let me know if there is something like this out ther...
So I'm using WCF, and want to document my interface(s) and services to give to another company for an internal app. What's the best way to document those interfaces? I'd prefer having the documentation inline with the code, and then have something prettify to output HTML, but am not sure if there's a recommended way to do it. Thanks....
Are there automatic ways to sync comments between an interface and its implementation? I'm currently documenting them both and wouldn't like to manually keep them in sync. UPDATE: Consider this code: interface IFoo{ /// <summary> /// Commenting DoThis method /// </summary> void DoThis(); } class Foo : IFoo { public...
I'm wondering if there is a defined standard for what the default action is of various HTML elements. I've looked at the W3C's HTML specification and while they are very precise with what attributes can be used with elements (and also some behavioural stuff such as exactly what gets included with form submission) there's nothing about t...
What artifacts / diagrams do use to document the flow of a web application taking into account links between static pages and how dynamic view components (html forms, JSP, Ajax, etc) interact with server-side components (Servlets, Struts actions, etc)? Do use UML diagrams? ...
I'm about to dive into the source code for the cgi.py module again because the MiniFieldStorage class is mentioned in the documentation, but not actually documented. It occurred to me that I have done this so many times that maybe I could write documentation for it. If I did, how should I submit it? ...
I've been working on an open source project on sourceforge a few months ago. One thing I noticed is that a well written summary could make a huge difference for the product. I literally saw traffic going to almost nothing when I made a poor change to project summary. One more thing I noticed is that not only summary has to be appealing,...
I'm building a desktop application in Flex/AIR, and one of the current items on my TODO list is to develop a help system. Throughout the GUI, there are little (?) buttons. When the user clicks one of those buttons, a HelpPanel appears, displaying some relevant information from the docs. Simple enough. But I'd really like to build a fu...
We recently started providing a data extract to clients via an XML. We have a schema (XSD) that defines the structure of this XML. I would like to include the documentation of the elements and attributes in the schema itself. The only thing I am finding is the very cumbersome "annotation" and "documentation" tags. So you take somethi...
Sphinx is a new documentation tool for Python. It looks very nice. What I'm wondering is: How suitable this is for documenting a C++ project? Are there any tools for converting existing documentation (e.g. doxygen) to Sphinx format? Are there online/downloadable examples of C++ projects that use Sphinx? Any tips from anyone who has use...
What is the official term for the basic object types available in the C#? I am creating API documentation and I need to explain any that one property of my API will accept any basic C# object (string, Int32, etc.) and it will not accept any complex data type (struct, class) ...
I wonder, how am I supposed to know which libraries I should include in my php.ini file when using a certain function. For instance, I just looked up pg_connect(), and I wonder which libraries I should include. I can think of php_pgsql.dll, but that's about it. Do I need others? I wouldn't know, since that doesn't seem to be documented...
I'm looking for something to turn my C# xml comments into documentation. I don't like chm's, nor msdn's look and feel. I love using the javadocs. They're easy to navigate, and everything is accessible. Is there a tool I can use to convert the comments in my code to a javadoc like look and feel. Is there something that does this? I've tr...