EzDevInfo.com

Learning Express for Node.js [closed]

Anyone have pointers to good resources for learning Express?

I'm aware of the documentation and the nodetuts.com videos. Curious if there are any other good resources out there.

Python documentation generator [closed]

I'm looking for a documentation generator for Python. I'm familiar with javadoc, and I tried Doxygen, but it seems quite unfit and counter-intuitive for Python.

Any ideas?

EDIT: Apart from the excellent answers below, you can also consult wikipedia's exhaustive Comparison of documentation generators.

How do you document your source code in Xcode?

I'm a Mac developer with a very strong Java background. I've documented my sources using Javadoc, a lot.

• What's the way to go with Cocoa and Xcode?
• Are there any documentation tools supplied together with Apple's Developer Tools?
• Is Doxygen the way to go? What are the alternatives?

Using roxygen2 and doxygen on the same package?

I have an R package that uses roxygen2. It has some C code in /src, and I have just started working with Doxygen. Are there any ways to combine the documentation, or integrate compiling with roxygen2? Any "best practices" for where to put the C code documentation?

Googling for roxygen2 and doxygen primarily leads to roxygen is similar to doxygen results. I have found a few packages with Doxyfiles, but no consistent organization. For example, lme4 has inst/doc/Doxyfile output to a folder called doxygen outside the lme4 source directory. There is also a Doxyfile in the root directory of the Matrix (but in previous releases was in inst. This documentation is also exported outside the package directory.

Is there any reason not to include the C documentation inside a package, or why is Doxygen so infrequently used within R packages, despite widespread use of C?

update: see related roxygen2 feature request

What is the standard Python docstring format?

I have seen a few different styles of writing docstrings in Python, is there an official or "agreed-upon" style?

RESTful JSON API Documentation Generator [closed]

I'm wondering if anyone has any experience or recommendations for tools that can be used to generate web pages that document and let you play with a RESTful JSON API. I'm thinking of something like the Github Developer API or Google API Console.

Looking around, I've found swagger from Wordnik, which looks good. But I'm wondering if there is anything else out there and what people's experience is with these tools. Thank you.

How can I create annotated source code like underscore.js?

I absolutely love the annotated source code that accompanies the underscore.js library:

1. How did they do that?
2. Is there a script that'll pull out the code comments and auto-create this kind of html documentation?

Python documentation standard for docstring

I am currently beginning with Python and I have a strong PHP background and in PHP I have took the habit of using javadoc as a documentation template.

I was wondering if javadoc has its place as docstring documentation in Python. Is something like this too elaborated to fit in the Python mindset or should I try to be as concise as possible?

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

And if I am a bit too exhaustive should I go with something like this instead (where most of the documentation doesn't get printed throught the __doc__ method):

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)

Does JavaScript have a standard for commenting functions? [closed]

I am currently writing some client side JavaScript code and wondering how to comment my functions.

I come from a C# background, where there is an officially recommended commenting style documented by Microsoft which I follow, which allows the compiler and other tools to auto-generate documentation.

Similarly, PHP's PHPDoc style is ubiquitous and on its way to becoming an official standard recommended by PHP-FIG.

Does JavaScript similarly have a universally accepted tool-chain, standard, or set of best practices that I can apply when commenting my functions?

How do I write a Technical Specification document for my software project?

I've seen a few questions around here saying that there's no need to write a beefy Technical Specification if the Functional Specification has all of the functionality. What about situations where the client has provided a Functional Specification and you need to turn around a Technical Specification from that document?

I understand that within a company writing smaller Technical Specifications focussed on specific parts of the solution is useful but if production of the Technical Specification is a project milestone/deliverable with client visibility what is the best way to approach writing one?

What if I don't know how exactly how I am going to implement a certain piece of functionality because I've not created it before? How can you write the Technical Specification in a way which this played down as not a catastrophe?

I am looking for templates/guidance/best practice suggestions and any real world experience that can help me create the kind of document that can be used for future projects of this nature.

What is self-documenting code and can it replace well documented code? [closed]

I have a colleague who insists that his code doesn't need comments, it's "self documenting."

I've reviewed his code, and while it's clearer than code which I've seen others produce, I still disagree that self-documenting code is as complete and useful as well commented and documented code.

Help me understand his point of view.

• What is self documenting code
• Can it really replace well commented and documented code
• Are there situations where it's better than well documented and commented code
• Are there examples where code cannot possibly be self-documenting without comments

Maybe it's just my own limitations, but I don't see how it can be a good practice.

This is not meant to be an argument - please don't bring up reasons why well commented and documented code is high priority - there are many resources showing this, but they aren't convincing to my peer. I believe I need to more fully understand his perspective to convince him otherwise. Start a new question if you must, but don't argue here.

Wow, quick response! Please read all the existing answers and provide comments to answers rather than add new answers, unless your answer really is substantially different from every other answer in here.

Also, those of you who are arguing against self documenting code -this is primarily to help me understand the perspective (ie, positive aspects) of self-documenting code evangelists. I expect others will downvote you if you don't stay on topic.

What are the new documentation commands available in Xcode 5?

One of Xcode 5's new features is the ability to document your own code with a special comment syntax. The format is similar to Doxygen, but appears to only support a subset of those features.

Which commands are supported, and which ones aren't?
Do any of their usages differ from Doxygen?

Good introduction to the .NET Reactive Framework [closed]

Aside from the Microsoft documentation, is there a good introduction and tutorial to the Microsoft Reactive (Rx) framework?

Also, what is a good example (with code) that Reactive makes easier of a programming problem that is challenging to solve using conventional asynchronous coding techniques?

Best Tips for documenting code using doxygen? [closed]

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 up your code, what are your MUST DOs and DO NOTs?
Please provide your top tips, one per answer to facilitate voting.

I am looking to define our whole approach to API documentation, including providing a template to get the rest of the team started. So far I have something like this:

/**
 * @file   example_action.h
 * @Author Me (me@example.com)
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

How to write a good README

I guess everyone has seen a README file, but I would like the definitive guide on how to write an excellent README file with the least amount of energy spent on it.

• What's a README file?
• What should I write in it?
• How exactly should I format it?

Side note:

As an example that satisfies "OMG this is an excellent README!" and "OMG this README is useless", I posted a link to gnome-cups-manager's README as a comment. The comment is now removed probably due to dead link so I copied the content to this gist.