cplusplus / cplusplus/draft

Alignment of declarations in library synopses

Open
#2,791 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

big
Dominant language
TeX
Stars
221
Forks
813
Avg merge
16h 4m
Merged PRs (30d)
36

Description

Declarations in library header and class synopses often go to great lengths to add spaces to align declarations in various ways. We're inconsistent about when we do so, and how we do so. These hand-alignments are fragile, and result in weird "stairsteps" between regions of local consistency. We should establish a consistent policy for which declarations, if any, we align.

Some examples drawn from [utilities]:

  • [utility.syn]:
    template<class T1, class T2>
      constexpr bool operator==(const pair<T1, T2>&, const pair<T1, T2>&);
    template<class T1, class T2>
      constexpr bool operator!=(const pair<T1, T2>&, const pair<T1, T2>&);
    template<class T1, class T2>
      constexpr bool operator< (const pair<T1, T2>&, const pair<T1, T2>&); 
    template<class T1, class T2>
      constexpr bool operator> (const pair<T1, T2>&, const pair<T1, T2>&); 
    template<class T1, class T2>
      constexpr bool operator<=(const pair<T1, T2>&, const pair<T1, T2>&);
    template<class T1, class T2>
      constexpr bool operator>=(const pair<T1, T2>&, const pair<T1, T2>&)
    
  • [allocator.traits]:
    template<class Alloc> struct allocator_traits {
      using allocator_type     = Alloc;
    
      using value_type         = typename Alloc::value_type;
    
      using pointer            = @\seebelow@;
      using const_pointer      = @\seebelow@;
      using void_pointer       = @\seebelow@;
      using const_void_pointer = @\seebelow@;
    
      using difference_type    = @\seebelow@;
      using size_type          = @\seebelow@;
    
      using propagate_on_container_copy_assignment = @\seebelow@;
      using propagate_on_container_move_assignment = @\seebelow@;
      using propagate_on_container_swap            = @\seebelow@;
      using is_always_equal                        = @\seebelow@;
    
      template<class T> using rebind_alloc = @\seebelow@;   // [ <---- ]
      template<class T> using rebind_traits = allocator_traits<rebind_alloc<T>>;
    
  • [template.bitset]:
    // 20.9.2.2, bitset operations
    bitset<N>& operator&=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator|=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator^=(const bitset<N>& rhs) noexcept;
    bitset<N>& operator<<=(size_t pos) noexcept;
    bitset<N>& operator>>=(size_t pos) noexcept;
    bitset<N>& set() noexcept;
    bitset<N>& set(size_t pos, bool val = true);
    bitset<N>& reset() noexcept;
    bitset<N>& reset(size_t pos);
    bitset<N>  operator~() const noexcept; // [ <---- ]
    bitset<N>& flip() noexcept;
    bitset<N>& flip(size_t pos);
    
  • [func.wrap.func]:
    template<class T>       T* target() noexcept;
    template<class T> const T* target() const noexcept;
    
  • [meta.type.synop]:
    template<class T>
      using remove_const_t    = typename remove_const<T>::type;
    template<class T>
      using remove_volatile_t = typename remove_volatile<T>::type;
    template<class T>
      using remove_cv_t       = typename remove_cv<T>::type;
    template<class T>
      using add_const_t       = typename add_const<T>::type;
    template<class T>
      using add_volatile_t    = typename add_volatile<T>::type;
    template<class T>
      using add_cv_t          = typename add_cv<T>::type;
    [...]
    template<class T>
      inline constexpr bool is_void_v = is_void<T>::value;
    template<class T>
      inline constexpr bool is_null_pointer_v = is_null_pointer<T>::value;
    template<class T>
      inline constexpr bool is_integral_v = is_integral<T>::value;
    template<class T>
      inline constexpr bool is_floating_point_v = is_floating_point<T>::value;
    template<class T>
      inline constexpr bool is_array_v = is_array<T>::value;
    template<class T>
      inline constexpr bool is_pointer_v = is_pointer<T>::value;
    

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the declaration formatting examples in utility.syn, allocator.traits, template.bitset, func.wrap.func, and meta.type.synop. Establish the consistent alignment policy requested in the issue, then apply it across the affected library synopses and verify that the examples no longer contain inconsistent spacing or stairsteps.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.