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

closed as too broad by gnat, Thomas Owens Dec 18 '18 at 17:31

Please edit the question to limit it to a specific problem with enough detail to identify an adequate answer. Avoid asking multiple distinct questions at once. See the How to Ask page for help clarifying this question. If this question can be reworded to fit the rules in the help center, please edit the question.

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

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