Uploaded image for project: 'C++ Driver'
  1. C++ Driver
  2. CXX-2827

Improve API Documentation for C++ Driver

XMLWordPrintableJSON

    • Type: Icon: Epic Epic
    • Resolution: Fixed
    • Priority: Icon: Unknown Unknown
    • 4.0.0, 3.11.0
    • Affects Version/s: None
    • Component/s: API Documentation
    • None
    • C Drivers
    • Not Needed
    • Done
    • API Docs Improvements
    • 5
    • 6.5
    • 7
    • 100
    • Hide

      2024-10-23: Project completed. Lower priority and out-of-scope work is moved to CXX-3127.

      Status update:

      • Merged part 2/2 of mongocxx examples.
      • Added redirects from "/current" pages to versioned URLs to improve search engine results.
      • Added sitemap for API pages to improve search engine results.

      2024-10-11: Changing end date to 2024-10-25

      Status update:

      • Merged part 1/2 of mongocxx examples.

      What goals are we targeting for the next two weeks?

      • Merge remaining mongocxx examples.

      Rationale for delays:

      • Review was delayed.

      2024-09-27: Changing end date to 2024-10-11

      What was accomplished since the last update?

      • Comprehensive examples for bsoncxx merged.
      • Removal of BSONCXX_ENUM to improve docs merged.
      • Fixes to `-Wdocumentation` warnings merged.

      What goals are we targeting for the next two weeks?

      • Add examples for mongocxx.

      Reasons for delays:

      2024-09-13: Changing end date to 2024-09-27

      What was accomplished since the last update?

      • Comprehensive examples for bsoncxx in review.
      • Removal of BSONCXX_ENUM to improve docs in review.

      What goals are we targeting for the next two weeks?

      • Add examples for mongocxx.

      Reasons for delays:

      • Discovery (and fixes) of several issues encountered when writing examples:
      • Assisting investigation with upstream Catch2 (#1292) and Doxygen (#3760) issues.

      2024-08-30: Changing end date to 2024-09-13

      What was accomplished since the last update?

      • Added support for testing examples against various server topologies.
      • Preliminary work to fix missing __cdecl: updated Catch2 to test.

      What goals are we targeting for the next two weeks?

      • Add missing __cdecl attributes and test.
      • Add examples to documentation.

      Reasons for delays

      • Adding examples exposed missing __cdecl attributes on public functions (CXX-3093).

       

      2024-08-16:  No change to end-date.

      What was accomplished since the last update?

      • Reorganization of API content merged.
      • Finished docs for directories, namespaces, and files.
      • Preliminary work for adding documentation examples merged.

      What goals are we targeting for the next two weeks?

      • Add comprehensive documentation examples.

      2024-08-02: Setting end date to 2024-08-30

      What was accomplished since the last update?

      • Fixed inconsistent use of Doxygen versions for consistent rendering on all C++ driver doc versions.
      • Docs of directories, namespaces, and files in progress. Eases navigation of API docs.
      • Fixed documentation warnings.
      • Reorganization of API content in review.

      What goals are we targeting for the next two weeks?

      • Finish docs for directories, namespaces, and files.
      • Start adding comprehensive documentation examples.

      Reasons for delays

      • Scope of project was increased to include comprehensive documentation examples.

      2024-07-19: Setting end-date to 2024-08-09

      Who actively worked on the project in the last two weeks?

      • Ezra Chung

      What was accomplished since the last update?

      • Relocation of contributing guidelines.
      • Fixed use of Doxygen directives.

      What goals are we targeting for the next two weeks?

      • Prepare docs for introduction of v1 namespace (related to CXX-1569).
      Show
      2024-10-23: Project completed. Lower priority and out-of-scope work is moved to CXX-3127 . Status update: Merged part 2/2 of mongocxx examples. Added redirects from "/current" pages to versioned URLs to improve search engine results. Added sitemap for API pages to improve search engine results. 2024-10-11: Changing end date to 2024-10-25 Status update: Merged part 1/2 of mongocxx examples. What goals are we targeting for the next two weeks? Merge remaining mongocxx examples. Rationale for delays: Review was delayed. 2024-09-27: Changing end date to 2024-10-11 What was accomplished since the last update? Comprehensive examples for bsoncxx merged. Removal of BSONCXX_ENUM to improve docs merged. Fixes to `-Wdocumentation` warnings merged. What goals are we targeting for the next two weeks? Add examples for mongocxx. Reasons for delays: Review of bsoncxx examples was delayed. Prioritized fix to libbson ( https://jira.mongodb.org/browse/CDRIVER-5732 ) discovered when writing examples. 2024-09-13: Changing end date to 2024-09-27 What was accomplished since the last update? Comprehensive examples for bsoncxx in review. Removal of BSONCXX_ENUM to improve docs in review. What goals are we targeting for the next two weeks? Add examples for mongocxx. Reasons for delays: Discovery (and fixes) of several issues encountered when writing examples: CDRIVER-5681 CDRIVER-5680 CXX-3098 CDRIVER-5710 Assisting investigation with upstream Catch2 ( #1292 ) and Doxygen ( #3760) issues. 2024-08-30: Changing end date to 2024-09-13 What was accomplished since the last update? Added support for testing examples against various server topologies. Preliminary work to fix missing __cdecl: updated Catch2 to test. What goals are we targeting for the next two weeks? Add missing __cdecl attributes and test. Add examples to documentation. Reasons for delays Adding examples exposed missing __cdecl attributes on public functions ( CXX-3093 ).   2024-08-16:  No change to end-date. What was accomplished since the last update? Reorganization of API content merged. Finished docs for directories, namespaces, and files. Preliminary work for adding documentation examples merged. What goals are we targeting for the next two weeks? Add comprehensive documentation examples. 2024-08-02: Setting end date to 2024-08-30 What was accomplished since the last update? Fixed inconsistent use of Doxygen versions for consistent rendering on all C++ driver doc versions. Docs of directories, namespaces, and files in progress. Eases navigation of API docs. Fixed documentation warnings. Reorganization of API content in review. What goals are we targeting for the next two weeks? Finish docs for directories, namespaces, and files. Start adding comprehensive documentation examples. Reasons for delays Scope of project was increased to include comprehensive documentation examples. 2024-07-19: Setting end-date to 2024-08-09 Who actively worked on the project in the last two weeks? Ezra Chung What was accomplished since the last update? Relocation of contributing guidelines. Fixed use of Doxygen directives. What goals are we targeting for the next two weeks? Prepare docs for introduction of v1 namespace (related to CXX-1569 ).

      Summary

      Users often report that the API docs for C++ driver is incomplete, poor to navigate/search and missing information and examples. This project aims to overhaul the API docs to solve the aforementioned problems.

      Motivation

      Who is the affected end user?

      Who are the stakeholders?

      How does this affect the end user?

      Are they blocked? Are they annoyed? Are they confused?

      How likely is it that this problem or use case will occur?

      Main path? Edge case?

      If the problem does occur, what are the consequences and how severe are they?

      Minor annoyance at a log message? Performance concern? Outage/unavailability? Failover can't complete?

      Is this issue urgent?

      Does this ticket have a required timeline? What is it?

      Is this ticket required by a downstream team?

      Needed by e.g. Atlas, Shell, Compass?

      Is this ticket only for tests?

      Is this ticket have any functional impact, or is it just test improvements?

      Cast of Characters

      Engineering Lead:
      Document Author:
      POCers:
      Product Owner:
      Program Manager:
      Stakeholders:

      Channels & Docs

      Slack Channel

      [Scope Document|some.url]

      [Technical Design Document|some.url]

            Assignee:
            ezra.chung@mongodb.com Ezra Chung
            Reporter:
            rishabh.bisht@mongodb.com Rishabh Bisht
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved:
              14 weeks, 2 days