I'm part of team working on SDK that is exposed with several programming languages - currently ObjC, C#, ActionScript, Java (Android) and later we'll have even more languages.
We want to have documentation which is made up of two parts:
Human readable documentation
API Reference
There are links between the two parts: from human readable docs we have links to specific classes or methods and from the API reference we may link to a document that explain the context in which the class or method is used.
We are currently use a combination of sphinx for human readable documentation and language specific tools for API such as doxygen or asdoc
I saw in LeapMotion they were able to generate a complete documentation for multiple programming-language (not human language) with cross links between programming-languages.
The Question
Does someone know how to accomplish such documentation system in a way we'll not have to duplicate each change in human readable docs to every language and have cross links between the languages?
I put together the Leap Motion documentation. I use Sphinx to create the package of docs and Breathe, a Sphinx plug-in, to basically import XML files generated by Doxygen into the Sphinx project for the doxygenated API references (C++, C#, Java, and Objective-C). For links from the so-called "human-readable" pages to the API references, I generate RST substitutions from the .tag files which Doxygen will generate for you. Links from the API reference to the "human-readable" pages are normal, relative hyperlinks (which I should add more of).
I use the conditional content features of Sphinx to generate a separate set of docs (both "human-readable" and API) for each programming language. Thus these articles can be customized for each programming language where needed and have the correct code examples for the current language. Because each doc set has the same structure, it isn't hard to switch from one language to another.
I did add some custom JavaScript to the page templates to help switch between languages.
tl;dr: Sphinx, Breathe, Doxygen and a small amount of custom JavaScript.
If you would like to discuss this further, you can post a question to our (Leap Motion) developer forum. I'll see it (Stackoverflow isn't the proper place for an ongoing discussion).
Hi Ido Ran,
Tools which you've specified are best in industry for documentation purpose,I am afraid there is no such tool yet which could provide both human and as well as API reference.Out of all my personal best is doxygen which is slighly of multi-use (human and API)..Hope this helps.
Related
I want to bind a different programming language to the Godot game engine. Is there an instructional document or video on this topic? For example, how was this project done: godot-rust. If I can learn the basics, I can succeed in working in a different language. Thanks.
In this answer I show you the different approaches to add language support in Godot 3.x (the situation will be somewhat different with Godot 4.0 and GDExtension - which replaces GDNative and hopefully means less custom builds), and I mention some languages that are supported by each of these approaches. However, this is not an exhaustive list of the languages.
First of all, Godot has official build-in support for GDScript and Godot's VisualScript (and Godot's shading language and its visual counterpart if those counts for you).
There are a few ways to use C++:
You can use it to create GDNative scripts (which are basically a wrapper around native calls that allow you to use them as scripts in Godot).
Or you can create modules (which are static libraries you can add in a custom Godot build).
And since Godot source is in C++, you don't have to restrict yourself to making modules if you are making custom builds.
In web builds Godot can interface with JavaScript via the JavaScript class. However, this approach does not allow you to add JavaScript scripts to Nodes, and so on.
Then there are languages that can only be added in custom builds of Godot, which is currently the official support for C#.
There are other non-official custom builds that offer language binding for languages such as Lua, Kotlin, TypeScript and JavaScript (this time allowing you to make scripts).
If you need to add a runtime, you would probably do this.
Some language take advantage of the fact that Godot's has official Mono support in order to support C#. This way you can, for example, use F# and Clojure.
They start by adding a C# project and then modify it so it uses another language. This is viable if your language already compiles to .NET.
Some other languages can be added as plugins that implement the PluginScript class via GDNative. This is the case of Python and Lua (again) which you can get from the asset library.
This is the most user friendly way to add language support to Godot, but it is limited to what you can do with PluginScript.
Addendum: Gil Barbosa Reis, author of the aforementioned Lua bindings, has an article series about its implementation stuffed away in the repository (in English and Portugueses): godot-lua-pluginscript/extras/articles/. It is probably the most comprehensive tutorial to date.
Other languages are added by means of taking advantage of GDNative (They basically mimic what you would do with C++). This is the case of Nim, Rust, D, Haskell, Go, Swift…
So that's how godot-rust works: make native libraries using rust and the godot-rust create and add them as if they were made in C++. For any language for which there are the means to make native libraries already, this is a good option.
Finally there is another way to add support for a language: a transpiler from that language to GDScript, which can be automated with an addon that might also be written in GDScript. This is the case of Lisp.
This last approach is mostly used for domain specific languages.
The official docs here provide your answer:
Godot officially supports GDScript, C/C++, C#.
Some 3rd party languages that can be used are: Rust, D, Python, Nim, and Go.
Here's the API doc of Stripe: https://stripe.com/docs/api
They seem to be using a three-columns template.
I am wondering whether they use some API blueprint renderer (markdown-to-html type of script) to generate it, similarly to Aglio: https://github.com/danielgtaylor/aglio
If they don't use any renderer, what other types of API blueprint renderers exist out there?
Stripe uses an in house doc generation tool, but Slate (https://github.com/tripit/slate) is a tool modeled off of Stripe's documentation. It looks quite similar and may be what you're looking for. I haven't used it myself so unfortunately I can't tell you much more.
If you want to stick to API Blueprint markdown flavor then check out apiary (http://apiary.io) as an alternative to aglio. It's not the three column layout but it is nice looking.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
The task
We'd like to maintain some developer's documentation for our .NET projects with the following criteria:
"Documents", ideally written in Markdown for providing information that's not closely related to a piece of code (like overview, FAQ).
Standard inline comments for code and API documentation. We do thus in form of standard inline (XML) comments on the classes/interfaces (primarily for IntelliSense support, secondarily for being able to generate an API reference) and would like to continue to do like that.
The documentation is contained in what it documents; e.g. if it's an overview of a solution then in the solution, if it's for a project then among the project's files, version controlled in the same way as the code (this is so the docs are close to what they document, so they are less prone for going out of date, and also this was docs are always "at hand").
Ability to auto-generate (from the CI server) a readable, compiled documentation for a whole project, including "documents" and inline comments for APIs.
An example
We've a project that's a component usable within a 3rd party system. For this project we have the following type of documentation:
Overview (what the project does, what are the aims)
Installation instructions
API documentation
Version history
We'd like to enable our developers and other developers to
- read this documentation from the project's source package and
- from a website.
Solutions we've looked at
Using a wiki (we tried Confluence): this is good for "document"-type of documentation (like overview or installation notes), but it lives independently from the project itself. It's another system to maintain and because it's not before one's eyes when doing development it can quickly go out of date. Also it's one more task to somehow integrate auto-generated API documentation into it.
Using Markdown files and storing them along the code: this is simple and documentation is always at hand and close to what it documents; however we somehow need to generate a publishable web package from these files and the source files' inline documentation.
So far doxygen looks like the solution capable of providing all these. Do you agree?
See "How to include custom files in doxygen".
Broadly speaking this is exactly what I am currently doing, and I'm using Doxygen.
However, I'm afraid I know nothing about .NET. The project I'm working on is a Java package, but includes API documentation extracted from the source, user guides, release records and things like deprecations.
The only thing out of our scope and in yours is Installation Guide, but that's really only because the developer only gets to read it after installation.
We have Jenkins CI building the document on every change.
The 'descriptive' text is all written in Markdown which Doxygen handles reasonably well.
Downsides: If you are familiar with the way Doxygen handles grouping of text for source code you may be confused that these commands don't work to group the blocks of text in Markdown. There are a few other specific oddities but you'll probably find most of them if you scan my own questions on the subject (here, here and here)
Upsides: (Things we've found useful that you've not mentioned)
We can also parse the 'doxygen' markup in the Java API to create a javadoc that IDE's such as Eclipse can use. This does mean we have to limit ourselves to javadoc-style command in the API docs but that's not a big limit.
We've included, under doxygen 'build switch', a manual for your developers on how to write the documentation for the manual (OK, this is slightly recursive!). This provides the recommended command subset to use, and whether (according to taste) you want people to use doxygen #subsection or Markdown ## for headings etc.
Hope that helps.
I'd suggest you try it; trialling a sample of each type of document section you need, to see if it will do the whole set of functions you need. Nothing more annoying documenting 90% then finding it won't do the last 10%.
Yesterday, Dave DeLong answered a question of mine. It wasn't the answer I was looking for, but in the question he mentioned an alternative way of generating doxygen-style documentation for Objective-C.
Before I could really look into it, someone (maybe Dave himself) noticed the answer didn't match the question that well and removed it. *poof* gone was the link to that documentation tool.
I can't remember the name, but I'm fairly certain it's neither HeaderDoc nor Doxygen itself.
Dave, you out there? What was that link again?
I'm clearly not Dave DeLong, but I'd use appledoc, it's pretty darn awesome!
Developer Page quote:
appledoc is command line tool that helps Objective-C developers generate
Apple-like source code documentation
from specially formatted source code
comments. It's designed to take as
readable source code comments as
possible for the input and use
comments as well as surrounding source
code to generate visually appealing
documentation in the form of HTML as
well as fully indexed and browsable
Xcode documentation set. Although
there are several tools that can
create HTML documentation for
Objective-C, all of those know to me
fall short in meeting the minimum of
goals described below.
Human readable source code appledoc is designed to keep source
code comments as readable as possible
even within your source code editor.
Cross references to objects and members Creating cross references to
classes, categories or protocols is
straightforward and automated as much
as possible.
Apple-like source code HTML documentation Generate appealing
HTML documentation with the same style
as Apple's.
Xcode documentation set creation Generate and install fully indexed and
browsable Xcode documentation sets.
Documentation set can also be
automatically installed to Xcode.
Single tool from sorce code to doc set Single tool to drive generation
from source code parsing to
documentation set installation
Easily customizable output appledoc gives you a lot of command
line switches so you can parameterize
output. If this is not enough, you can
change any or all of the template
files to suit your needs.
100% Objective-C implementation The whole appledoc is written in
Objective-C, so you can easily change
it using familiar language and tools.
This also make debugging much simpler
and effective.
Whenever I ask people about the difference between an API and a library, I get different opinions. Some give this kind of definition, saying that an API is a spec and a library is an implementation...
Some will tell you this type of definition, that an API is a bunch of mapped out functions, and a Library is just the distribution in compiled form.
All this makes me wonder, in a world of web code, frameworks and open-source, is there really a practical difference anymore? Could a library like jQuery or cURL crossover into the definition of an API?
Also, do frameworks cross over into this category at all? Is there part of Rails or Zend that could be more "API-like," or "libraryesque"?
Really looking forward to some enlightening thoughts :)
My view is that when I speak of an API, it means only the parts that are exposed to the programmer. If I speak of a 'library' then I also mean everything that is working "under the hood", though part of the library nevertheless.
A library contains re-usable chunks of code (a software program).
These re-usable codes of library is linked to your program through APIs
(Application Programming Interfaces). That is, this API is an interface to library through which re-usable codes are linked to your application program.
In simple term it can be said that an API is an interface between two software programs which facilitates the interaction between them.
For example, in procedural languages like C, the library math.c contains the implementations of mathematical function, such as sqrt, exp, log etc. It contains the definition of all these functions.
These function can be referenced by using the API math.h which describes and prescribes the expected behavior.
That being said, an API is a specification (math.h explains about all the functions it provides, their arguments and data they return etc.) and a library is an implementation (math.c contains all the definitions of these functions).
API is part of library that defines how it will interact with external code. Every library has API, API is sum of all public/exported stuff. Nowadays meaning of API is widened. we might call the way web site/service interact with code as API also. You can also tell that some device has API - the set of commands you can call.
Sometimes this terms can be mixed together. For example you have some server app (like TFS for example). It has API with it, and this API is implemented as a library. But this library is just a middle layer between you and not the one who executes your calls. But if library itself contains all action code then we can't say that this library is API.
I think that Library is a set of all classes and functions that can be used from our code to do our task easily. But the library can contain some of its private functions for its usage which it does not want to expose.
API is a part of library which is exposed to the user. So whatever documentation we have regarding a library, we call it an API Documentation because it contains only those classes and functions to which we have access.
we have first to define an interface ...
Interface :is the means by which 2 "things" talk to each other and exchange information. "things" could be a (1) human or (2) a running code of any sort (e.g. library ,desktop application , OS , web service ... etc).
if a human want to talks to a program he need Graphical user interface (GUI) or command line interface (CLI). both are types of interfaces that humans (but not programs) would like to use.
if however a running code (of any sort) want to talk to another running code (of any sort) it doesn't need or want a GUI or CLI ,it rather need an Application Programming Interface (API).
so to answer the original poster question : library is a type of running code and the API is the means by which this running code talk to other running codes.
In Clear and concise language
Library: Collection of all classes and methods stored for re-usability
API: Part of library classes and methods which can be used by a user in his/her code.
According to my perspective, whatever the functions are accessible to invoker , we can called as api in library file, library file having some of the functions which is private , we cannot access them ..
There are two cases when we speak or think of API
Computer program using library
Everything else (wider meaning)
I think, that in the first case, thinking in terms of API is confusing. It's because we always use a library. There are only libraries. API without library doesn't exist, while there's a tendency to think in such terms.
How about The Standard Template Library (STL) in C++? It's a software library.
You can have different libraries with the same API, meaning set of available classes, objects, methods, functions, procedures or whatever terms you like in some programming language. But it can be said, that we have different implementation of some "standard" library.
Some analogy may be that: SQL is a standard but can have different implementations. What you use is always some SQL engine which implements SQL. You may follow only standard set of features or use some extended, specific to that implementation.
And what "under the hood" in library is not your concern, except in terms of differences in efficiency by different implementations of such library.
Of course I'm aware, that this way of thinking is not what is a "generally binding standard". Just a lot of new terms have been created, that are not always clear, precise, intuitive, that brings some confusion. When Oracle speaks about Collections. It's not library, it's not API, it's a "Collections Framework".
Hello brothers and sisters.
Without using technical terms I would like to share my understanding regarding API and library.
The way I distinguish 'library' and 'API' is imagining a situation where I go to a book library. When I go there, I request a book which I need to a 'librarian' without knowing how a entire library is managed.
I make a simple relation between them like this.
Library = A book library which has a whole system and staffs to manage books.
API = A librarian who provides me a simple access to a book which I need.