documentation

I have a C program with multiple files, so I have, for example, stuff.c which implements a few functions, and stuff.h with the function prototypes. How should I go about documenting the functions in comments? Should I have all the docs in the header file, all the docs in the .c file, or duplicate the docs for both? I like the latter approach, but then I run into problems where I'll update the docs on one of them and not the other (usually the one where I make the first modification, i.e. if I modify the header file first, then its comments will reflect that, but if I update the implementation,

I am using Sphinx to generate the documentation for a project of mine. In this project, I describe a list of available commands in a yaml file which, once loaded, results in a dictionary in the form {command-name : command-description} for example: commands = {"copy" : "Copy the highlighted text in the clipboard", "paste" : "Paste the clipboard text to cursor location", ...} What I would like to know, is if there is a method in sphinx to load the yaml file during the make html cycle, translate the python dictionary in some reStructuredText format (e.g. a definition list ) and include in my

I have an open-source project ( here ) whose documentation is currently in French. The documentation is generated from XML comments in code, using Sandcastle. Now I would like to translate the documentation to English and provide documentation in both languages, but I don't really know where to start... Do I need to extract the XML comments from the code and put them in a separate file? If yes, are there any tools to automate the process? I'm using Sandcastle Help File Builder to build the documentation; do I need to create a separate project to build the doc in English, or can it be done from

After many happy years coding in notepad++ and sublime, I've been advised to give a PHP IDE a go. I'm trying out phpStorm and it seems nice. The code completion and documentation is a great feature but isn't working out for me when magic methods are used. Is there a work around to get phpStorm to understand what's going on in magic methods? Our situation is something like this: abstract class a { public static function __callStatic($method,$args) { if(strpos($method,"get_by_") === 0) { //do stuff } elseif(strpos($method,"get_first_by_") === 0) { //do stuff } elseif($method == "get_all") { //do

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. Barry Wark Doxygen is probably the most widely used option. Because it's not just for ObjC (doxygen supports many other languages), the development is lively and the community quite strong. HeaderDoc (now an open source project), by comparison appears to have largely stagnated. HeaderDoc only produces HTML output, while doxygen also produces PDF, LaTeX and many other output forms besides HTML. Even Apple seems to recommend

I am currently writing a small framework that will be used internally by other developers within the company. I want to provide good Intellisense information, but I am not sure how to document thrown exceptions. In the following example: public void MyMethod1() { MyMethod2(); // also may throw InvalidOperationException } public void MyMethod2() { System.IO.File.Open(somepath...); // this may throw FileNotFoundException // also may throw DivideByZeroException } I know the markup for documenting exceptions is: /// <exception cref="SomeException">when things go wrong.</exception> What I don't

I'm going to design a RESTful API soon, thus I need to describe it in order to enable other people to start implementing clients using it. I've looked around a bit, but unfortunately, I've not found any standardized form of describing web-based RESTful services. What I'am looking for is something like JavaDoc, although it don't have to be generated out of any sort of code. I'm also not talking about something like WADL, I rather want to have some human-readable documentation I can hand out. Due to the nature of RESTful web-based services, it should be quite easy to standardize a documentation.