7

I'm currently looking into API documentation generation tools and I noticed that apparently there are no efforts going on in standardization.

Javadoc style is kind of an ubiquitous convention... it is used for Java (duh), PHP (PHPDocumentor, doxygen, Stubbles), C/C++ (doxygen again)... and there is even IDE support for it even in other languages that are not java.

Even NaturalDocs which has a completely different syntax for documentation has some compatibility for it.

So my question is: are there any efforts going on in standardizing in-code documentation syntax?, which can in turn be used for documentation generators or language metadata across different languages?.

albert
  • 155
  • 5
dukeofgaming
  • 13,943
  • 6
  • 50
  • 77
  • 2
    what's documentation? – Reactgular May 08 '12 at 01:56
  • 3
    Three programmers using the same language and the same tools on the same platform generally won't agree about how to format their code. You want them to agree on how to write documentation? – Caleb May 08 '12 at 02:22
  • 1
    @Caleb I'm mostly talking about a standard to have the same (or similar) input for documentation generation tools, where there would be common ground for code metadata... but why not?, there are code standards. – dukeofgaming May 08 '12 at 02:27
  • What does standardization have to do with being usable across different languages? – Pubby May 08 '12 at 03:13
  • 6
    [Mandatory XKCD reference](http://xkcd.com/927/). – AProgrammer May 08 '12 at 04:57
  • Doxygen is about as much of a standardization as you're going to get. It's hard enough to standardize a single language must less something that applies to all languages! – Gort the Robot May 08 '12 at 04:57
  • @Caleb, sometimes even _one_ programmer can't agree on how to format his/her code. :) – Randall Cook May 08 '12 at 06:42
  • @dukeofgaming I was mostly joking, but it does seem unlikely that a single way to encode documentation will ever emerge. Different programmers have different needs, and both programmers and tool vendors are always looking for better ways to do things. Doxygen is a great example of a system that's widely used and a sort of standard, but as you point out there are others as well. The *reason* there are so many others is that programmers don't form a homogeneous group -- we all have different preferences and requirements. Vive la difference! – Caleb May 08 '12 at 06:54
  • 1
    The reason JavaDoc is popular is because Sun 1) set a very good example with the runtime javadoc and 2) made it available to everyone in the JDK. For a given community to accept anything you need something similar for that community. –  May 08 '12 at 06:58
  • doc format / style that would fit both Java and x86 assembly languages, would be damaging for programmer's productivity – gnat May 08 '12 at 07:48

1 Answers1

3

I am going to go out on a limb and say that there are none, and even if there was one, it would be ignored because the programming community is too diverse and opinionated to all agree on something. That being said, the JavaDoc/Doxygen family is as close as we are likely to get. We might see a few large camps develop, but that's it.

Randall Cook
  • 2,470
  • 19
  • 19