Skip to content

Using robots to fix/update docs part 3: com.h #654

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.

Sign up for GitHub

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

Open
Duncan Horn (dunhor) wants to merge 7 commits into
base: master
Choose a base branch
from
Open

Using robots to fix/update docs part 3: com.h #654

Changes from 1 commit
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
459c02b
Docs for com.h
dunhor Jul 20, 2026
35cbf8e
Skill update
dunhor Jul 20, 2026
9f57e0d
Merge remote-tracking branch 'origin/master' into dunhor/com_docs
dunhor Jul 20, 2026
1f995ab
Namespace no longer necessary
dunhor Jul 20, 2026
11ca9f0
Remove docs for stream_position_saver's defaulted constructors
dunhor Jul 20, 2026
725f851
Merge branch 'master' into dunhor/com_docs
dunhor Jul 20, 2026
0bcee95
Merge branch 'master' into dunhor/com_docs
dunhor Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 30 additions & 14 deletions include/wil/com.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -922,16 +922,16 @@ class com_ptr_t
// Error-policy driven forms of com_ptr

#ifdef WIL_ENABLE_EXCEPTIONS
//! COM pointer, errors throw exceptions (see @ref com_ptr_t for details)
//! COM pointer, errors throw exceptions (see @ref wil::com_ptr_t for details)

@jonwis Jon Wiswall (jonwis) Jul 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Interesting; the docs system doesn't know about namespaces?

@dunhor Duncan Horn (dunhor) Jul 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, so apparently this is related to the change in #655 that pulled the end-of-wil-namespace curly brace outside of the @endcond comment. So, with that fix, the explicit namespace here is not necessary - Doxygen resolves the namespaces correctly.

And apparently, even without the explicit namespace here, Doxygen will make an educated guess based off which types are documented, so previously it was just a warning; the HTML was still the same and the links worked.

The net impact of this change is that the HTML now mentions wil::com_ptr_t instead of com_ptr_t. I guess it's personal preference which one you like more - since this is all documentation for WIL, the explicit wil namespace is a bit unnecessary.

I'll complete that PR first and then tidy this one up to remove the explicit namespaces and verify that the warnings are gone.

template <typename T>
using com_ptr = com_ptr_t<T, err_exception_policy>;
#endif

//! COM pointer, errors return error codes (see @ref com_ptr_t for details)
//! COM pointer, errors return error codes (see @ref wil::com_ptr_t for details)
template <typename T>
using com_ptr_nothrow = com_ptr_t<T, err_returncode_policy>;

//! COM pointer, errors fail-fast (see @ref com_ptr_t for details)
//! COM pointer, errors fail-fast (see @ref wil::com_ptr_t for details)
template <typename T>
using com_ptr_failfast = com_ptr_t<T, err_failfast_policy>;

Expand Down Expand Up @@ -1223,7 +1223,7 @@ inline bool operator<=(TLeft* left, const com_ptr_t<TRight, ErrRight>& right) WI
//! forwarding reference template that can be used as an input com pointer. That input com pointer is allowed to be any of:
//! * Raw Pointer: `T* com_raw_ptr(T* ptr)`
//! * Wil com_ptr: `T* com_raw_ptr(const wil::com_ptr_t<T, err>& ptr)`
//! * WRL ComPtr: `T* com_raw_ptr(const ::Microsoft::WRL::ComPtr<T>& ptr)`
//! * WRL ComPtr: `T* com_raw_ptr(const Microsoft::WRL::ComPtr<T>& ptr)`
//! * C++/CX hat: `IInspectable* com_raw_ptr(Platform::Object^ ptr)`
//!
//! Which in turn allows code like the following to be written:
Expand Down Expand Up @@ -1794,13 +1794,15 @@ inline U^ cx_dynamic_cast(T&& ptrSource) WI_NOEXCEPT

#if (NTDDI_VERSION >= NTDDI_WINBLUE)
#ifdef WIL_ENABLE_EXCEPTIONS
//! Agile reference to a COM interface, errors throw exceptions (see @ref com_ptr_t and @ref com_agile_query for details)
//! Agile reference to a COM interface, errors throw exceptions (see @ref wil::com_ptr_t and @ref wil::com_agile_query for
//! details)
using com_agile_ref = com_ptr<IAgileReference>;
#endif
//! Agile reference to a COM interface, errors return error codes (see @ref com_ptr_t and @ref com_agile_query_nothrow for
//! details)
//! Agile reference to a COM interface, errors return error codes (see @ref wil::com_ptr_t and @ref wil::com_agile_query_nothrow
//! for details)
using com_agile_ref_nothrow = com_ptr_nothrow<IAgileReference>;
//! Agile reference to a COM interface, errors fail fast (see @ref com_ptr_t and @ref com_agile_query_failfast for details)
//! Agile reference to a COM interface, errors fail fast (see @ref wil::com_ptr_t and @ref wil::com_agile_query_failfast for
//! details)
using com_agile_ref_failfast = com_ptr_failfast<IAgileReference>;

//! @name Create agile reference helpers
Expand Down Expand Up @@ -1913,12 +1915,14 @@ namespace details
} // namespace details

#ifdef WIL_ENABLE_EXCEPTIONS
//! Weak reference to a COM interface, errors throw exceptions (see @ref com_ptr_t and @ref com_weak_query for details)
//! Weak reference to a COM interface, errors throw exceptions (see @ref wil::com_ptr_t and @ref wil::com_weak_query for details)
using com_weak_ref = com_ptr<IWeakReference>;
#endif
//! Weak reference to a COM interface, errors return error codes (see @ref com_ptr_t and @ref com_weak_query_nothrow for details)
//! Weak reference to a COM interface, errors return error codes (see @ref wil::com_ptr_t and @ref wil::com_weak_query_nothrow
//! for details)
using com_weak_ref_nothrow = com_ptr_nothrow<IWeakReference>;
//! Weak reference to a COM interface, errors fail fast (see @ref com_ptr_t and @ref com_weak_query_failfast for details)
//! Weak reference to a COM interface, errors fail fast (see @ref wil::com_ptr_t and @ref wil::com_weak_query_failfast for
//! details)
using com_weak_ref_failfast = com_ptr_failfast<IWeakReference>;

//! @name Create weak reference helpers
Expand Down Expand Up @@ -2008,6 +2012,10 @@ HRESULT com_weak_copy_nothrow(T&& ptrSource, _COM_Outptr_result_maybenull_ IWeak

#pragma region COM Object Helpers

//! Returns whether the given COM object is agile (that is, whether it implements `IAgileObject`).
//! @tparam T A raw interface pointer, any wil `com_ptr`, or a WRL `ComPtr`.
//! @param ptrSource The object to test.
//! @return `true` if the object implements `IAgileObject`, `false` otherwise.
template <typename T>
inline bool is_agile(T&& ptrSource)
{
Expand Down Expand Up @@ -3058,7 +3066,9 @@ class stream_position_saver
m_stream.reset();
}

//! Move constructor; transfers the saved stream position.

@jonwis Jon Wiswall (jonwis) Jul 20, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are these comments necessary? Maybe put a better comment on the type itself, so what these methods do is implied?

@dunhor Duncan Horn (dunhor) Jul 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, probably. I'll have it update the skill to wrap things like this w/ @cond/@endcond, though that means these constructors are no longer mentioned in the docs, which is probably fine.

@dunhor Duncan Horn (dunhor) Jul 20, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, without comments, Doxygen will emit a warning, so there's effectively two options:

  1. Add docs to these declarations
  2. Wrap the declarations with begincond/endcond

I've changed to just wrapping with begincond/endcond. The "downside" is that these won't appear in the generated docs at all, even as undocumented. But given we can probably count the number of people using Doxygen with WIL on 0-1 hands, probably not a big deal to just omit them.

stream_position_saver(stream_position_saver&&) = default;
//! Move assignment operator; transfers the saved stream position.
stream_position_saver& operator=(stream_position_saver&&) = default;

stream_position_saver(const stream_position_saver&) = delete;
Expand All @@ -3082,6 +3092,8 @@ namespace details
} // namespace details
/// @endcond

//! Unique RAII type that clears an object's site by calling `IObjectWithSite::SetSite(nullptr)` on destruction, breaking
//! the site cycle.
using unique_set_site_null_call = wil::unique_com_call<IObjectWithSite, decltype(details::SetSiteNull), details::SetSiteNull>;

/** RAII support for managing the site chain. This function sets the site pointer on an object and return an object
Expand Down Expand Up @@ -3378,6 +3390,9 @@ template <typename err_policy>
class com_timeout_t
{
public:
//! Establishes the call timeout on the current thread for this object's lifetime.
//! @param timeoutInMilliseconds The per-call timeout, in milliseconds, after which blocked cross-apartment calls are
//! canceled.
com_timeout_t(DWORD timeoutInMilliseconds) : m_threadId(GetCurrentThreadId())
{
const HRESULT cancelEnablementResult = CoEnableCallCancellation(nullptr);
Expand All @@ -3397,6 +3412,7 @@ class com_timeout_t
}
}

//! Returns whether the timeout was successfully established (the underlying threadpool timer was created).
operator bool() const noexcept
{
// All construction calls must succeed to provide us with a non-null m_timer value.
Expand Down Expand Up @@ -3433,14 +3449,14 @@ class com_timeout_t
// Error-policy driven forms of com_timeout

#ifdef WIL_ENABLE_EXCEPTIONS
//! COM timeout, errors throw exceptions (see @ref com_timeout_t for details)
//! COM timeout, errors throw exceptions (see @ref wil::com_timeout_t for details)
using com_timeout = com_timeout_t<err_exception_policy>;
#endif

//! COM timeout, errors return error codes (see @ref com_timeout_t for details)
//! COM timeout, errors return error codes (see @ref wil::com_timeout_t for details)
using com_timeout_nothrow = com_timeout_t<err_returncode_policy>;

//! COM timeout, errors fail-fast (see @ref com_timeout_t for details)
//! COM timeout, errors fail-fast (see @ref wil::com_timeout_t for details)
using com_timeout_failfast = com_timeout_t<err_failfast_policy>;

#endif // WINAPI_FAMILY_PARTITION(WINAPI_PARTITION_DESKTOP | WINAPI_PARTITION_SYSTEM)
Expand Down
Loading