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.
I am supposed to do a IVR project using Pronexus. After downloading their DLLs, my code hit COMExceptions regularly. I have searched the net and learned about Component Object Model. Now I am in trouble as I do not know how should I write my codes to extend from the DLLs that is accessing unmanaged codes.
So my question is, can someone point me to a direction how can I proceed from here? Should I learn how to code with COM libraries? Any good sources to recommend?
Found a clue from msdn.microsoft.com/en-us/library/ms973872.aspx (good read for developer new to Component Object Model)
Here I am looking for a conceptual solution, plus some guidance. This is not an query that specifies an 'error in code/compilation/execution...' etc. Pl bear with the lengthy post.
My product is a desktop product written in VB.NET.
Another central team in office maintains a java code that does some computations, and releases jar to be used by whomever wants it. This team published APIs exposed by jar.
Users of this java jar were so far java developers, so everything was smooth so far.
Now, I am required to use the same jar and hence make calls to those exposed java APIs so that 'code is one, and used by any-and-many'.
Kindly pass on any useful links/code samples that helps me achieve this.
P.S.
1. I do not have a chance to go to any third party tools to make the bridge between Java & .net.
I am getting little bit understanding about JNI for such purposes, but am not getting a solid code sample that explains what should I do on C++ side to make a call to java functions.
And my team could put efforts to call C++ wappers from VB.NET
Thanks in advance,
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.
I was wondering if there were a way to extract information from an objective-c app, static or dynamic library and/or framework?
Information such as an array of class names without instantiating or running the target.
I've checked google and the apple developer documentation and haven't found anything.
Frank
F-script appears to be able to do what you want, but I'm no expert. Check out www.fscript.org.
If you want to extract classes from an application/dynamic library, there is a handy tool called ClassDump.
It can even generate the header files in order to get an overview of the classes, protocols, etc.
If you want to do it at runtime, then take a look at the source code to learn how to load and parse the different mach-o segments.
This is an excellent starting point for reverse-engineering Cocoa apps:
http://culater.net/wiki/moin.cgi/CocoaReverseEngineering
It mentions F-Script, class-dump, and a few others.