search

bytedeco / javacpp-presets

The missing Java distribution of native C++ libraries
Other
2.65k stars 736 forks source link

Please convert markdown-style comments to JavaDoc #146

Open lukehutch opened 8 years ago

lukehutch commented 8 years ago

There is lots of good documentation auto-extracted from the TensorFlow header files here:

https://github.com/bytedeco/javacpp-presets/blob/master/tensorflow/src/main/java/org/bytedeco/javacpp/tensorflow.java

However, the docs use line comments, not JavaDoc comments, so the documentation is not visible in popups in Eclipse etc.

In this case, the comments are in MarkDown format. It would be great if you could specify that (1) line comments extracted from header files should be converted to JavaDoc block comments; and (2) (optionally) that comments should be parsed as MarkDown, and converted into JavaDoc's own weird HTML variant. (e.g. prettyprint blocks in the TF docs should be wrapped in <code>, etc.)

Thanks!

saudet commented 8 years ago

JavaCPP already converts much of Doxygen, including Markdown, into what can be represented with Javadoc. The problem though is that a lot of the comments in Tensorflow are not in Doxygen format, even though they are supposed to be: https://github.com/tensorflow/tensorflow/issues/14

So, it looks like we have to figure out how to parse those g3doc comments properly. It's not obvious to me how those differ from normal non-documentation comments. Help would be welcome!

saudet commented 8 years ago

Any updates on this? Would be nice to know what to do about that.