documentation

Basic requests are: human readable / text format (for easy version control) online (for collaboration) easy formatting (markdown ok, html is too much) strict formatting (so authors don't invent new types of titles, bullets etc.) exportable to PDF, HTML easy backup and deployment (so we can "deploy" to customers site as read only version) We are thinking about using some kind of wiki engine, but it would need to use files for storage or have other means of "deployment" to customer and be easy to install/maintan. Also, it would have to be free / cheap (confluence is way too expensive) Any

I have some code that returns a promise object, e.g. using Q library for NodeJS. var Q = require('q'); /** * @returns ??? */ function task(err) { return err? Q.reject(new Error('Some error')) : Q.resolve('Some result'); } How to document such a return value using JSDoc? Even if they don't exist in Javascript, I found that JSdoc understands "generic types". So you can define your custom types and then use /* @return Promise<MyType> */ . The following result in a nice TokenConsume(token) → {Promise.<Token>} with a link to your custom Token type in the doc. /** * @typedef Token * @property {bool}

I'm using sphinx and the autodoc plugin to generate API documentation for my Python modules. Whilst I can see how to nicely document specific parameters, I cannot find an example of how to document a **kwargs parameter. Does anyone have a good example of a clear way to document these? I think subprocess -module's docs is a good example. Give an exhaustive list of all parameters for a top/parent class . Then just refer to that list for all other occurrences of **kwargs . After finding this question I settled on the following, which is valid Sphinx and works fairly well: def some_function(first,

I'm starting an open source Python project shortly and I'm trying to decide in advance how to write my docstrings. The obvious answer would be using reStructuredText and Sphinx with autodoc, because I really like the idea of simply properly documenting my code in my docstrings then have Sphinx automatically construct an API doc for me. The problem is the reStructuredText syntax it uses - I think it's completely unreadable before it's rendered. For instance: :param path: The path of the file to wrap :type path: str :param field_storage: The :class:`FileStorage` instance to wrap :type field

Recently our team is working on a new project with node.js. It is not difficult to start working with node.js. But now we're all just start to use this new technique and have little experience in such event-based development. So I am wondering if there are any books, blogs or other materials covering the topics of "best practice" of node.js, just like "effective c++", "effective java", etc. schaermu Well, i can just support you with the findings that helped me the most when learning "how to node": DailyJS : JavaScript in general, contains a lot of node.js specific posts/tutorials HowToNode :

I'm currently using JSDoc Toolkit to document my code, but it doesn't quite fit - namely, it seem to struggle with describing namespaces properly. Say you have two simple classes in each their files: lib/database/foo.js : /** @class */ function Foo(...) {...} /** @function ... */ Foo.prototype.init(..., cb) { return cb(null, ...); }; module.exports = foo; And then something inherited lib/database/bar.js : var Foo = require('./foo'); /** * @class * @augments Foo */ function Bar(....) {...} util.inherits(Bar, Foo); Bar.prototype.moreInit(..., cb) { return cb(null, ...); }; In the generated

I'm writing a specification for a RESTful API for a new internal web service. It's not hugely long and fairly simple, but even so, it's my first time using strict REST (as opposed to cheating for practical reasons - avoiding PUT and DELETE because they're a pain in PHP, and so on). I was wondering if there were any standard methods or best practices for documenting a REST interface? I want the rest of the team to understand it at a glance, and for anyone that wants to write a client to be able to do so without understanding the underlying code. Sure, REST APIs should ideally use HATEOAS and be

Please identify the most popular lightweight markup languages and compare their strengths and weaknesses. These languages should be general-purpose markup for technical prose, such as for documentation (for example, Haml doesn't count). See also: Markdown versus ReStructuredText JasonSmith I know of three main languages used commonly in the greater programming and tech community: Textile, Markdown, and reStructuredText. All three can be learned in a couple of hours or "winged" with the cheat sheet nearby. Textile Used by Redmine and the Ruby community 113 questions currently tagged on Stack

TeX/LaTeX is great, I use it in many ways. Some of its advantages are: it uses text files, this way the input-files can be diffed and many tools exist to work with text it is very flexible it has a stable layout: if I change something at the start of the document, it doesn't affect other things at the end of the document it has many extensions to reach different goals (a successor would start without extensions, but would have a good extension-system) you can use standard build control tools to support complicated documents (thanks dmckee) you can encapsulate solutions and copy&paste them to