20

PEP 8 -- Style Guide for Python Code categories comments and document strings (a.k.a. docstrings) under comments sections. Comments Block Comments Inline Comments Documentation Strings Block comments generally apply to some (or all) code that follows them and are indented to the same level as that code. Inline comments are unnecessary and in fact ...


14

An abstract should cover the whole paper. It reports what the paper is for, what you did and the conclusion. E.g. This paper explores the hypothesis that you can't teach an old dog new tricks. The experiment classifies new tricks as tricks the dog hasn't learned before. Six dogs were used in the trial. Three old, three not old. Two tricks were used. One ...


13

Start with the style guidelines from Oracle for Javadoc. While those guidelines are written for the Javadoc tool (and the Java language) in particular, the principles there apply to the corresponding tools for other languages. (I've seen this kind of documentation for C++, C#, and JavaScript APIs.) This answer augments that style guide. I'm going to ...


12

Introduction The Biggest reason documentation is written is to help developers learn about the software system and give them a reference to the tools they are using. This is a broad question and I must admit most of the tips I will give will be my opinions and things I've found helpful. Below are some guidelines and design aspects you can use to help ...


8

Code comments and docstrings have different purposes and audiences: Developers write docstrings to describe the function's behaviour. Other developers, who use this function, read docstrings to find about the meaning of parameters, the pre- and post-conditions, possible exceptions etc. If you're writing an API, you may want to publish docstrings as a part ...


7

API stands for "application programming interface". API documentation is addressed to programmers who will use that interface to accomplish some task. While all technical writing is addressed to someone who's trying to accomplish some task, and while some of those people (and tasks) are deeply technical, API documentation has some special considerations: ...


6

In my opinion, any answer looks messy. One "sentence" with capitals halfway through bugs me; so does a line starting without a capital. Personally, I would restructure the entire thing to avoid the issue entirely: Example 1 Currently, line 57 of camera.py looks like this: camera.start_recording('foo.h264', quantization=25) In this line, the ...


5

Automated systems such as Sandcastle and Swagger are good at converting code syntax into documentation. Those will produce marginal documentation. What they don't do is add insight into the calls. Rarely does a method exist by itself. There are always additional notes needed, caveats explained, side affects, clarifications for each the parameters, return ...


4

Look at API documentation for C#, such as that on the Microsoft site (see here), or check out one of the multitude of repositories on Github. Basically, API document the ways users interact with your product. You have to specify fields, classes, methods, constants, etc. Look at the Java API to see a systematic way to do this and then adapt it to your ...


4

Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlooks the fact that API documentation is used by a range of people. It's short sighted by both the guys who says it and for the writing team to assume the documentation is only for the experienced developers. It has to appeal to both the ...


4

I can understand the reasoning from both sides. A complete quick start is essential to ensure that the reader has sufficient information to see the product running correctly, and is able to demonstrate and present a sample default use case to the user, without these the casual reader will not know whether to bother reading further because they will be unable ...


4

The value of adding code examples to documentation depends on the example itself as well as the API or library in question. I work with a widely used software library, and we have a stated expectation that our users are well beyond the "Hello, World!" level. We have examples and guides that build components incrementally, where each part is self contained ...


4

I think it really boils down to the fact that there are two different audiences/purposes for the documentation. Documenting private methods probably isn't super important when it comes to generating documentation for your application overall. In that setting, you're probably more concerned about the purpose of the components more so than the implementation....


3

If the API you're going to document is a REST API, Tom Johnson has this excellent free online course, Documenting REST APIs. If that doesn't fit your needs, Stack Overflow has a couple of topics that might also be interesting: C# Doc Generator has a list of tools to consider. Creating great API doc: Tools and techniques. An important API doc tool that'...


3

The writing of the abstract and introduction of a paper is a very difficult task because if you have 1000 readers most of them read these parts and your paper evaluation strongly depends on these parts too. In abstract, you should give an overall view of the paper including the importance and necessity of the paper topic (the first line of the abstract), ...


3

We solved this by adding overview files in Markdown format into the source tree and making one small configuration change. In Doxyfile, we set GENERATE_TREEVIEW to yes. This enables the sidebar table of contents, which is needed if you want these overview files to actually show up somewhere. (Normally doxygen just emits code elements -- classes, ...


3

As a software developer (C#, .NET, yada, yada), Monica's answer resounded nicely with me. (I don't have enough rep yet to comment on it, so my additions have to go here.) I would add that I find great value in API documentation that is as explicit as it can be, but not overburdened with meaningless details. Further, it's very important to me that the ...


3

I would say an API needs reasonable examples of use, and needs attention paid (or links provided) to other closely related elements of the API; even if it is just like "See xyyGraphInit". You want your programmers to be able to use the product quickly and without having to read the whole dang thing five times. I can (and have had to) read through a list of ...


3

First of all, let’s make it clear, what API means. API stands for Application Programming Interface. API is a set of tools, communication protocols, and subroutine definitions for building software. Generally speaking, API is a kind of communication channel that allows two separate programs to communicate. How does it work? API is also a part of your daily ...


2

This surely depends on the specific tool that you are using. The only tool that I am familiar with that meets your description is Javadoc, so I want to be cautious not to make assumption about how other tools might work. But with Javadoc, there is a built-in way to describe parameters. The whole point of Javadoc is to have a consistent way to document an ...


2

It's difficult to do a head-to-head comparison because it's not very often that you'll find someone who has experience using both Mashery and Apigee. So, from the Mashery side, I can comment on what is available because I am deeply familiar with the solution. For documenting an API, Mashery has two product features that come standard to all clients: (1) ...


2

Ask your readers to point you to API documentation that they do find helpful. Get clarification from your readers. Do they mean that the "javadoc" is too vague? incomplete? poorly worded? Or do they mean that they can understand the reference doc, but it doesn't help them write an application using the API. Here's my edit of the original example. I had to ...


2

Abstract An abstract can be defined as a summary of the information in a document. It should not exceed 250 words It should be written in one paragraph. It should be written in the past tense as it refers to work done. Long words should be followed by its abbreviation which would be used through out the abstract and paper. It should not cite any references ...


2

The main challenge of having multiple writers is dealing with conflicts -- either you have to lock files to prevent concurrent edits (as Word does), or you need a way to compare and merge changes. Locking files can be pretty limiting (especially as your group grows), but source-control systems give you the latter if you don't use a binary file format. I ...


2

In test-driven development the emphasis is on writing tests that clarify what code should do, rather than extensive documentation. Future maintainers of the code can then ensure that the code continues to exhibit the behavior it should by virtue of the tests. The way tests are named form a type of documentation of the proper behavior of the code. Here is an ...


2

How do you document X? It depends on who's going to read the document. As a rule of thumb I use to look at my documentation from two perspectives; the system perspective and the audience perspective. The system perspective deals with what system is being documented, and if several systems should be dealt with in one document or if a system should be ...


2

Eric Woodruff took over Sandcastle in 2012. Due to reservations Microsoft's legal department had related to transferring the project itself, Woodruff forked the project as Sandcastle Help File Builder. Microsoft published a statement on the project website, stating that they discontinued development of the project and suggested users moved on with Woodruff's ...


2

The purpose of API documentation is to explain how to use the API. Providing sample code of how to use key features is a good way to demonstrate the intended usage. A good example of this is the ZMQ guide. It has example code in a large number of languages to go with each of the of the concepts discussed. They combat the bloat by displaying links to the ...


2

There are different types of examples and they serve different purposes. One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes too simple (simplistic), but this example should use defaults where possible and not bite off too much --...


Only top voted, non community-wiki answers of a minimum length are eligible