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?.

  • 2
    what's documentation? – Reactgular May 8 '12 at 1: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 8 '12 at 2: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 8 '12 at 2:27
  • 6
    Mandatory XKCD reference. – AProgrammer May 8 '12 at 4:57
  • 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. – user1249 May 8 '12 at 6:58

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.

| improve this answer | |

Not the answer you're looking for? Browse other questions tagged or ask your own question.