Hi, I'm in the process of generating API docs for an in-house web app that's undergoing some expansion. It's a DHTML project, with a mix of both some OO and mostly procedural PHP, and purely procedural Javascript. At the moment, it's pretty much all documented for the appropriate doc generators (phpdocumentor and jsdoc), but the two wer...
Where is it customary to write the in-code documentation of classes and methods? Do you write such doc-blocks above the corresponding class/method in the header (.hpp) file, or within the source (.cpp) file? Is there a widely respected convention for such things? Do most C++ projects do it one way rather than the other? Or sho...
We all have the good habit of documenting our code, right? Nowadays, in-code documentation itself has a syntax. It's almost like a programming language onto itself. The questions are: What (How many) documentation syntax specifications exist? Is there a standard documentation syntax? Who is defining this standard? Is there an of...
The title says it all. But here a few points which concern me: How do you maintain documentation which will be released to customers? What about docs which are for internals use? How to document packages/classes/methods/APIs? How to ensure maintainability? e.g. check-in criteria, code review checklist item, automation. ...
Hi, I'm looking for a web based application to easily compile easily navigatable software documentation from videos, audio, images and text. I seem to remember having come across such a system a couple of months ago (not a wiki), but I'm unable to relocate it. Does anyone know what I'm talking about, or have any good suggestions for su...
This is really just re-asking this question asked about Visual Studio 2008. Does VS2010 offer any feature to get rid of the CS1591 compiler warning for auto-generated code? CS1591: Missing XML comment for publicly visible type or member To quote the question for VS2008: This is an annoyance more than a problem. My project contain...
I use a lot of illustrations, diagrams and equations to document C++ and python codes, and a way to do this is to inline them with doxygen. The problem is that, when coding, they are not directly available in the code (unless I use ascii-art for this purpose). Is there an automatic, quick and fast way to, while coding, view the generate...
I am currently developing lua scripts for a new application which requires the extension to be xx_lua. I have luadoc working fine for .lua extensions and I know I could simply rename the files to the lua extension create the documents and rename them back, but personally I would prefer a more elegant solution. Is is possible to get lu...
I created a webservice and would like to generate documentation for the API. So I looked into Enunciate downloaded the maven enunciate plugin. However I get the below error on compile as the webservice annotations are on my interface class that my POJO implements rather than the POJO itself. I don't want to clutter the POJO by adding ...
Before Java methods we have something like: /** * Takes a number and returns its square root. * @param x The value to square. * @return The square root of the given number. */ public float getSqrt(float x) { ... } Does this have a name (like docstrings in Python)? ...
When I run sbt doc, it results in a nice but nonetheless pretty basic documentation. Is it possible to a) include the source files for the class definition and b) inherit the docstrings for inherited members? What do I need to add to my project definition? (It’s a Lift project, so most important would be to have the inherited Lift d...
I'm using EpyDoc (with reStructuredText) to document my Python project and produce HTML output. EpyDoc automatically truncates long lists of attributes in UML diagrams (generated with the --graph=umlclasstree option), helpfully placing a clickable ... marker that doesn't link to anything or seem to trigger any JavaScript events. For ex...
Hi. At work, the database is not documented at all. Furthermore, the stored procedures, functions and views are all encrypted, this rules out a lot of tools that document these objects for you. All I have are the plain .SQL files that generate the database, schemas, tables, functions and all. I'd like to know, is there a tool that can r...
I'm trying to find a tool that generates HTML documentation for my Javascript source code. Does anyone know if the tool that Google uses to generate the interface at the following URLs is open source? Would I be able to generate similar output? http://closure-library.googlecode.com/svn/docs/class_goog_proto2_Serializer.html http://c...
Someone asked me this, what will be a good aproach? Design a model of a spreadsheet (like excel), but don’t be afraid, do it very simple! We only need a basic class diagram with no more than 5 or 6 classes. It should have the following features: The sheet will only manage numeric data There will be two types of cells: Cells that con...
I'm using the "manual" document class of Sphinx and I'm quite happy with how the Latex Output looks like, except for the page header. It contains the title of my paper, as well as a "Release 1". Since I'm writing a paper and not a documentation, I clearly don't need the release information. Unfortunately, it is very hard to find inform...
Are there any existing solutions to create documents in Silverlight? Looking to create purchase orders, contracts, etc. Printing is a desired feature. ...
I know that PHPDoc exists, but phpdoc wants you to put comments in your PHP files so that it can parse them... What I want is something different: Suppose that I have 10 PHP classes... all I want is a script that can read those classes and automatically generate a representation of those class structures, i.e. what classes are in them, ...
We are currently looking for ways to help the non-programming members of the sysadmin group familiarize themselves with Python scripts used for day-to-day sysadmin tasks. Does anyone have any suggested documentation tools or best practices that we might find useful for this purpose? Edit to address S.Lott's comment: First, my apologie...
I have following pod which I used with getopt::long: =head1 SYNOPSIS foo [OPTION]... [URL]... =head1 OPTIONS =over 20 =item B<-h, --help> Print a brief help message and exits. =item B<-i, --input=FILE> Reads from FILE =back =cut and when I provides -h it produces: Usage: foo [OPTION]... [URL]... Options: -h, --hel...