Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Doc] C++ client's doc is poor #9282

Closed
BewareMyPower opened this issue Jan 22, 2021 · 7 comments
Closed

[Doc] C++ client's doc is poor #9282

BewareMyPower opened this issue Jan 22, 2021 · 7 comments
Assignees
Labels
type/enhancement The enhancements for the existing features or docs. e.g. reduce memory usage of the delayed messages
Milestone

Comments

@BewareMyPower
Copy link
Contributor

BewareMyPower commented Jan 22, 2021

Is your enhancement request related to a problem? Please describe.
The C++ client's doc is poor, a lot of interfaces are not well documented. For example, a lot of setters/getters have no document, see http://pulsar.apache.org/api/cpp/2.7.0-SNAPSHOT/classpulsar_1_1_producer_configuration.html for example. Users cannot get some default config values and its definition.

Describe the solution you'd like
Improve the documents. At least we should add documents for those interfaces.

Additional context
I'm working on new API of Producer::send recently (see #9176), when the PR is pushed, it can be treated as an example.

@BewareMyPower BewareMyPower added the type/enhancement The enhancements for the existing features or docs. e.g. reduce memory usage of the delayed messages label Jan 22, 2021
@BewareMyPower BewareMyPower changed the title [Doc] C++ client [Doc] C++ client's doc is poor Jan 22, 2021
@BewareMyPower
Copy link
Contributor Author

As the generated docs in my local environment, here's an example from #9287

截屏2021-01-22 下午10 45 28

As we can see, we can link ProducerConfiguration's related methods from Producer#send. However it requires these external methods have JavaDoc style comments. If not, these methods cannot be linked, like the current C++ API website:

截屏2021-01-22 下午10 50 12

The methods with dark bold text are not documented and have no link.

@Anonymitaet Anonymitaet added this to the 2.8.0 milestone Mar 1, 2021
@Anonymitaet Anonymitaet added the doc-required Your PR changes impact docs and you will update later. label Mar 1, 2021
@Anonymitaet
Copy link
Member

Anonymitaet commented Mar 2, 2021

Hi @BewareMyPower I've added descriptions (suggestion mode) for the methods in the ProducerConfiguration.h, could you please help review?

https://docs.google.com/document/d/1SjO8SCVcbCMuEVW-HI1kf_jJjy-Ej5yFZoY9g4jUAQQ/edit

Feedback before 3/5 is highly appreciated, thanks.

@Anonymitaet
Copy link
Member

Hi @BewareMyPower, I've added descriptions for the methods in the following files:

  • ClientConfiguration.h
  • ConsumerConfiguration.h
  • ReaderConfiguration.h

Could you please help review?

Feedback before 3/31 is highly appreciated, thanks!

@BewareMyPower
Copy link
Contributor Author

@Anonymitaet OK

@Anonymitaet
Copy link
Member

Anonymitaet commented Apr 8, 2021

@BewareMyPower I've added more descriptions for various classes in C++ client API - 0408 and C++ client API - 0409

Could you please review and give feedback before 4/13? Many thanks!

@BewareMyPower
Copy link
Contributor Author

@Anonymitaet OK, I'm a little busy these days and may give some feedbacks on 4/11 or 4/12.

@Anonymitaet
Copy link
Member

@BewareMyPower OK, take your time and thanks for your help.

@Anonymitaet Anonymitaet removed the doc-required Your PR changes impact docs and you will update later. label Apr 15, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
type/enhancement The enhancements for the existing features or docs. e.g. reduce memory usage of the delayed messages
Projects
None yet
Development

No branches or pull requests

2 participants