2

For some reasons, i want to document an API but I don't want to write the documentation directly inside the source code as it is now widely done. I'm looking for a documentation generator tool which could take as input a documentation file and be able do fetch function prototype from source code and check the consistency with the documentation. Do you know any tool that could do that ?

Valentin Perrelle
  • 1,303
  • 1
  • 10
  • 17
  • 1
    What language is the code written in? It might be very relevant. You should tag your question with it. – Chris Mantle Aug 17 '13 at 16:37
  • 1
    For Now c++. Anyway, I'm also curious to have a more general answer as I might need this kind of tools for other languages as well. – Valentin Perrelle Aug 17 '13 at 16:39
  • 2
    Documentation kept "away from" the source-file tends to be less likely to be updated when the source is updated (and given how often you find that the code and comments are out of sync when they ARE in the same file), I'd say that's not a good plan. – Mats Petersson Aug 17 '13 at 16:47
  • There are many synchronization problems anyway. I don't believe this is a problem related to "where the documentation is located". If you want to distribute a library, spend all the time that is needed to keep the API documentation consistent. Note that i'm talking about documenting the API, not the library internal. – Valentin Perrelle Aug 17 '13 at 16:51
  • You should use doxygen where the documentation goes into the header, and not the source file. Is that okay for you? – László Papp Aug 17 '13 at 16:58
  • Here, I consider headers as a part of the source code. I'm looking for a documentation generator which will only read headers to check consistency w.r.t. the documentation. – Valentin Perrelle Aug 17 '13 at 17:02
  • Quoting a fellow (actually no quote but in my words): "The documentation text is mostly wrong, only the source gives insight" –  Aug 17 '13 at 17:09
  • I agree with the quotation. However, i can't possibly imagine my library would be used if I say to my user "read the library source". It is not constructive. We didn't achieve yet to imagine a programming language which completely mirrors the mind shortest path to understand the behavior of a program. We tried though, and there are many modeling languages, even with iterative refinements. However, the shortest way for a library user to understand how to use a library is a short text in plain english side by side with examples. – Valentin Perrelle Aug 17 '13 at 17:16
  • Again, please note that i'm talking about documenting an API. Code documentation is a much larger subject, which include documenting internal, function prototypes and architecture. None of these subjects are part of my question. Please stop this digression. – Valentin Perrelle Aug 17 '13 at 17:16
  • What is the point of splitting source code and documentation? IF you use doxygen, then it will take documentation from source, and compose it in several available formats. You don't need to send API users to source code, just distribute files generated by doxygen as documentation, and anyone willing to read source anyway will have a bonus of documentation at hand. – j_kubik Aug 17 '13 at 18:35
  • There are several reasons. The first one is that the structure of the documentation wont necessarily follow the structure of the source/header. You might want to have an input file which is structured like your documentation, not like your source. Furthermore, there is not necessarily a 1:1 relation between prototype documentation and source. You may want to write a documentation for a set of function (most likely when there is overloading) which is sometime done with copy/paste (worse case) a special copydoc attribute, or with the mean of references. (best case) – Valentin Perrelle Aug 17 '13 at 18:43
  • Anyhow, this is just an illustration of the fact that the structure of the documentation may not be the same as the structure of the code. There may be other reasons. The person writing the code might not be the same as the person writing the documentation. This doesn't necessarily imply desynchronization, as the function behavior may have been mathematically specified before. Inserting the code in comments might be unhandy as there might be restrictions in the encapsulating language, or in code conventions. – Valentin Perrelle Aug 17 '13 at 18:48
  • You might also want to describe different interfaces for the same API but for different client languages. You might want then to reuse common parts of the text to comment all interfaces. The documentation input is thus not strictly related to one programming language and shouldn't be included in the source code. You might as well want to translate the documentation. For this reason or another, the documentation may become large, and you may want to rely on modularity of the documentation system. (e.g. one input file for one translated language) I may find other reasons if you let me some time. – Valentin Perrelle Aug 17 '13 at 18:52

1 Answers1

6

Doxygen can document code also when documentation text is outside it source. Just create a souce file whose text is a comment, containing the headers:

For example, if you have

SOURCE.H

void func();

you can add

SOURCE.DOX

/**
   \function void func()
   Your usual doxygen text here.
*/

And generate the documentation making doxygen to accept both .h and .dox files.

Emilio Garavaglia
  • 20,229
  • 2
  • 46
  • 63
  • I agree with the previous comments that it would be a bad idea not to write it into the source code. I think we should convince the author to change his mindset. :) – László Papp Aug 17 '13 at 17:03
  • 2
    @Laszlo Papp: This is not a discussion about "where comments should be put". Stackoverflow is better suited for Q&A format. – Valentin Perrelle Aug 17 '13 at 17:04
  • @Emilio Garavaglia: Thank you for this answer. – Valentin Perrelle Aug 17 '13 at 17:06
  • 2
    @LaszloPapp: One thing are comments, other are documents. The documentation of an API can be an entire book. Putting such a content in between the source makes the source itself unreadable: how can I follow a logic if every code line is 100 lines distant? The book is not written with the source, but after the source had become a release candidate, to explain a USER how to use the API. It's a completely different purpose and business than the few word written inside the source just to justify its shape and form to a source reader and API developer. – Emilio Garavaglia Aug 17 '13 at 19:29
  • I'm playing with Doxygen. It seems it suffers from the cons of any system built to produce documentation from source. For instance, there is no convenient way to document a group of overloaded functions http://stackoverflow.com/questions/11860660/grouping-overloads-in-doxygen Do you have insights about that ? – Valentin Perrelle Aug 18 '13 at 07:45
  • @ValentinPerrelle: You can manage "groups" with the @{ and @} keywords. Also \defgroup \addtogroup and \ingroup can paly tha game quite well: you define function to belong to groups than document a group. Give a look to the doxigen manual about "Grouping" – Emilio Garavaglia Aug 18 '13 at 07:53
  • I didn't achieve yet to apply your solution. I told doxygen that .dox file were markdown files. I believe this to be more convienient as it removes the need to encapsulate the documentation into comments, and allow a more liberal syntax to be used. (no problem with stars or indentation) I could document a class, but not the methods. For the methods, doxygen would say "Warning: member with no name found." while the same documentation put into comments at the end of the header file containing the class would work as expected. – Valentin Perrelle Aug 20 '13 at 15:26
  • Ah, this is precisly why it doesn't work, it seems it has to be treated like a C file with comments. – Valentin Perrelle Aug 20 '13 at 15:35