[
https://issues.apache.org/jira/browse/CASSANDRA-324?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=12775921#action_12775921
]
Jonathan Ellis commented on CASSANDRA-324:
------------------------------------------
Looking at the output of the java and python generated code, it's clear that ..
thrift sucks. Shocker.
It should move @param documentation in structs to the generated constructors
but it does not.
It hardcodes an Attributes: section in the generated pydoc for structs that
ignores @params.
It doesn't wrap lines.
The last one we can fix but the rest, not so much.
For this patch I think we should
- wrap lines
- use @param, @returns in method docstrings
- It's hard to say what to do with structs because all the options suck. We
could do plain-text documentation of the parameters but that is poorly
integrated with javadoc and pydoc as above. html table docs are not very
human-readable, but the generated html actually looks pretty good. Leaving it
out entirely and referring to a web page kinda sucks too...
Thoughts?
To see what it looks like to a python user, after -gen py, cd gen-py and
>>> from cassandra import ttypes
>>> help(ttypes)
> Add documentation to Thrift interface
> -------------------------------------
>
> Key: CASSANDRA-324
> URL: https://issues.apache.org/jira/browse/CASSANDRA-324
> Project: Cassandra
> Issue Type: Improvement
> Components: Documentation & website
> Reporter: Michael Greene
> Assignee: Gary Dusbabek
> Priority: Minor
> Fix For: 0.5
>
> Attachments: 324-v1.patch
>
>
> We should be using the doctext feature of Thrift to document all of our
> enums, structs, and services.
> Rather than leaving individual wrapper libraries to document the interface,
> it should be consolidated into one place (the .thrift file). It can then be
> used to generate javadocs for the stuff that gets placed in gen-java,
> documentation for the Thrift-generated client libraries, or generate nifty
> html using Thrift's own --gen html.
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
