That's it. If you want to document a function or a class, you put a string just after the definition. For instance: def foo(): """This function does nothing.""" pass But what about a module? How can I document what a file.py does? ...
Since I pound API docs pretty hard when I'm coding, I like to have them on my local disk. jQuery.com lists a lot of sources for browsing the API documentation online, but I haven't found anywhere I can download an HTML bundle as a TAR or ZIP file. Is such a bundle available? EDIT: I should have said that I want an HTML version. UPDATE:...
I've recently started a new project and I'm using C# for the first time. I've found that while Visual Studio is helpful in creating C#'s XML comments to document your classes and methods, there's not much you can do to generate MSDN or Javadoc style documentation. Google tells me that Visual Studio 2003 included a tool to generate such...
My team is starting to document our C code using doxygen, paying particular attention to our public API headers. There appears to be a lot of flexibility and different special commands in doxygen, which is great, but it's not clear what's a good thing and what's a bad thing without trial and error. What are your favourite ways to mark ...
I have allways made a point of writing nice code comments for classes and methods with the C# xml syntax. I allways expected to easily be able to export them later on. Today I actually have to do so, but am having trouble finding out how. Is there something I'm missing? I want to go Menu->Build->Build Code Documentation... EDIT: This i...
I am using D2007 and am trying to document my source code, using the HelpInsight feature (provided since D2005). I am mainly interested in getting the HelpInsight tool-tips working. From various Web-surfing and experimentation I have found the following: Using the triple slash (///) comment style works more often than the other docum...
I would like to find out from other's experience what is the best way to capture screencasts that include code and cuts to the program in action, and then present those screencasts online so that the code is still legible, and ideally making the most efficient use of display real estate. What capture tools work well for this? I've trie...
I like doxygen to create documentation of C or PHP code. I have an upcoming Python project and I think I remember that Python doesn't have /* .. */ comments and also has its own self-documentation facility which seems to be the pythonic way to document. Can I just use doxygen? Anything particular to be aware of? I have done some coding...
Back in the days of Unix, you couldn't even close a software without reading the man page first. Then came Mac and Windows with consistent menu layout and keyboard shortcuts, but you still saw paper user manuals shipped in the shrinkwrap box, which described each and every single operation possible in the app. After the Internet, help fi...
When I do a search, the results are a bit hit-and-miss; many of the 'documentation' sites seem more advertising than information. What are the good sources of Javascript language info on the web? ...
It feels like an artifacts of an earlier days, but UML sure does have its use. However, agile processes like Extreme Programming advocates "embracing changes", does that also means I should make less documents and UML models as well? Since they gives the impression of setting something in stone. Where does UML belongs in an Agile develo...
Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of "value limits" as well as the classic documentation ? Note: I am not talking about comments within the code By "value limits", I mean: does a parameter can support a null value (or an empty String, or...) ? does a 'return value'...
Has anybody got this to actually work? Documentation is non existent on how to enable this feature and I get missing attribute exceptions despite having a 3.5 SP1 project. ...
I find that for most software projects, documentation is often oriented towards the process of development the software, rather than supporting and maintaining it. This is particularly true when using agile methodologies, which emphasize minimalistic documentation. The issue with development-oriented documentation is that it tends to be...
As suggested, I have closed the question posed here and have broken it up into separate questions regarding code documentation to be posed throughout the day. The first question I have is, what are the guidelines you follow when you write documentation for a method/function/procedure? Do you always do doc-comments or do you try to le...
As suggested, I have closed the question posed here and have broken it up into separate questions regarding code documentation to be posed throughout the day. The first part: How do you document your methods? This question is about documentation as it relates to automated tests, especially unit tests. Do you think it is appropriate ...
In C# documentation tags allow you to produce output similar to MSDN. What are a list of allowable tags for use inside the /// (triple slash) comment area above classes, methods, and properties? ...
As suggested, I have closed the question posed here and have broken it up into separate questions regarding code documentation to be posed throughout the day. This is the final question in the series. The first part: How do you document your methods? The second part: Are tests valid documentation? This question has to do with wh...
There are various documents describing threading on Solaris/Linux, but nowwhere describing the Windows implementation. I have a passing interest in this, it seems strange that something so critical is (seemingly) not documented. Threading is not the same on different OS' - "Write Once, Run Anywhere" isn't true for threading. See http:/...
What kind of documentation you'd recommend to support for Agile project? What are the core metrics you use to detect amount of documentation needed? Do you think you can store all of project info as TFS work items? ...