search

robotpy / robotpy-cppheaderparser

DEPRECATED: use cxxheaderparser instead
Other
123 stars 39 forks source link

[issue 5] : First Documentation sample #17

Closed FreeYourSoul closed 5 years ago

FreeYourSoul commented 5 years ago

https://github.com/robotpy/robotpy-cppheaderparser/issues/5

Still, need some completion (on parameter types for instance) and adding example for each section would be really helpfull (and fast to do). Better this documentation than nothing as watching example to understand how it works is painfull..

auscompgeek commented 5 years ago

I would much rather see docs generated from the source code if possible, otherwise we run the risk of the docs being forgotten and becoming out-of-date when the code changes.

FreeYourSoul commented 5 years ago

Well, I think it can be an eternal debate ^^, I think is a PR is asking a change without updating the documentation accordingly, it shouldn't be merged. Having the doc generated by the code usually pollute the code (too much in my opinion). In the end, it's a matter of taste. :)

auscompgeek commented 5 years ago

The biggest thing this currently needs is simple API documentation, which can be easily generated from the source code.

We could keep high-level prose out of the source code if we feel it doesn't really fit in the code, but our focus right now should be documenting what attributes/methods there are, etc.

virtuald commented 5 years ago

My taste is that where it makes sense, docs should be generated by the code.

I suspect for this project there's a happy medium somewhere -- we should have autogenerated API docs, probably accompanied by a separate document that serves as a users guide (ideally integrated with the API docs).

virtuald commented 5 years ago

Thanks for your efforts. I've added a readthedocs site to host documentation for this project. It autogenerates API docs from the source code. I updated some of it with some of your notes. I'd love to see the documentation get better -- feel free to refactor this PR and make it work with the Sphinx content!

Documentation can be found at https://cppheaderparser.readthedocs.io/en/latest/