search

linux-test-project / ltp

Linux Test Project (mailing list: https://lists.linux.it/listinfo/ltp)
https://linux-test-project.readthedocs.io/
GNU General Public License v2.0
2.33k stars 1.02k forks source link

Generate test library documentation from LTP source headers #262

Open metan-ucw opened 6 years ago

metan-ucw commented 6 years ago

We do have quite a bit of documentation in the headers in a parseable format at this point so it makes sense to produce a formal API description out of that. The problem here is to choose right tool for the job.

The format that has been chosen accidentally is more or less compatible with kernel-doc or gtk-doc.

I've tried to play with a doxygen shortly, it's kind of awkward for C code, however when configured correctly it can produce reasonable output. The downside is that we will have to reformat the comments we have since they are not compatible with javadoc format which doxygen seems to accept and I do not like the verbosity of javadoc that pollutes the comments with keywords.

I've also looked into the sphinx+kernel-doc and while it being compatible with our comment format it's very limited compared to doxygen and the implementation is more of a horrible hack than anything else at this point.

There is also gtk-doc tool that is supposed to work with what we have, I haven't evaluated that one yet.

richiejp commented 6 years ago

I had a quick play with gtk doc and could not get it to parse tst_fuzzy_sync.h correctly and it is not clear why. I think it would be a struggle to get it working with the entire project.

I have used http://jessevdk.github.io/cldoc/index.html in the past which has a nice clean format and works really well (it uses libclang), but all comments are doc comments unless you start a comment with - or possibly if it is in a place which does not make sense to be a doc comment. I am not sure if that would be a good or a bad thing. The big problem though is that it's dependencies are a bit outside the LTP's current set of dependencies, probably a lot more so than doxygen.

metan-ucw commented 6 years ago

@richiejp Well I do not care that much about dependencies for the documentation generator since I do not expect everyone use it, however I would like to choose something that is mature enough and I'm not sure that this is the case for cldoc.

pevik commented 2 years ago

I guess we have docparse, thus we can close it now.

metan-ucw commented 2 years ago

@pevik quite contrary, this is about using a tool such as doxygen to generate the LTP library API documentation. This is completely out of scope of test documentation work we have done.

pevik commented 2 years ago

Ah, sorry, I didn't read carefully.