Lugar de documentação é no terminal

Introdução


Apesar de gostar bastante do cppreference nem sempre ele acaba sendo a melhor solução para mim. Principalmente porque trocar do meu editor para um browser é uma operação um tanto quanto lenta, sem falar em todas as distrações que um browser geralmente traz consigo.

Por isso eu resolvi procurar uma solução que fosse melhor para o meu gosto e acabei descobrindo que é possível acessar a documentação do C++ diretamente do terminal. Uma vantagem acidental desta solução é a possibilidade de realizar pesquisas sem acesso a internet. Não que eu costume ficar sem acesso mas de qualquer maneira é bom saber disso.

Instalação


Para instalar a documentação das bibliotecas padrão do C++ basta apenas instalar o pacote libstdc++-doc. No Fedora 24 isto pode ser realizado com o seguinte comando:

user@localhost ~/ sudo dnf isntall libstcdc++-docs

Utilização


Agora que já temos o pacote devidamente instalado podemos acessar seu conteúdo através do comando man.

user@localhost ~/ man std::vector
std::vector< _Tp, _Alloc >(3)          Library Functions Manual          std::vector< _Tp, _Alloc >(3)

NAME
       std::vector< _Tp, _Alloc > - A standard container which offers fixed time access to individual
       elements in any order.

SYNOPSIS
       Inherits std::_Vector_base< _Tp, _Alloc >.

   Public Types
       typedef _Alloc allocator_type
       typedef __gnu_cxx::__normal_iterator< const_pointer, vector > const_iterator
       typedef _Alloc_traits::const_pointer const_pointer
       typedef _Alloc_traits::const_reference const_reference
       typedef std::reverse_iterator< const_iterator > const_reverse_iterator
       typedef ptrdiff_t difference_type
       typedef __gnu_cxx::__normal_iterator< pointer, vector > iterator
       typedef _Base::pointer pointer
       typedef _Alloc_traits::reference reference
       typedef std::reverse_iterator< iterator > reverse_iterator
       typedef size_t size_type
       typedef _Tp value_type

Lembre-se que você pode utilizar /foo para pesquisar por ‘foo’.

Provavelmente a parte mais interessante será a Member Function Documentation. Lá você encontrará a definição de métodos como o size():

   template<typename _Tp, typename _Alloc = std::allocator<_Tp>> size_type std::vector< _Tp, _Alloc
       >::size () const [inline],  [noexcept]
       Returns the number of elements in the vector.

       Definition at line 655 of file stl_vector.h.

       Referenced by __gnu_parallel::__shrink(), __gnu_parallel::__shrink_and_double(), std::vector<
       _Tp, _Alloc >::emplace(), __gnu_parallel::list_partition(), std::vector< _Tp, _Alloc
       >::operator=(), std::operator==(), std::operator>>(), and std::regex_traits< _Ch_type
       >::transform_primary().

Com isso descobrimos que o método size() não precisa de nenhum parâmetro e que ele retorna um valor do tipo size_type. Além disso também temos uma breve descrição do método.

Podemos olhar para outro exemplo, ainda na mesma classe, o método reserve():

   template<typename _Tp , typename _Alloc > void vector::reserve (size_type __n)
       Attempt to preallocate enough memory for specified number of elements.

       Parameters:
           __n Number of elements required.

       Exceptions:
           std::length_error If n exceeds max_size().

       This function attempts to reserve enough memory for the vector to hold the specified number of
       elements. If the number requested is more than max_size(), length_error is thrown.

       The advantage of this function is that if optimal code is a necessity and the user can
       determine the number of elements that will be required, the user can reserve the memory in
       advance, and thus prevent a possible reallocation of memory and copying of vector data.

       Definition at line 66 of file vector.tcc.

       References std::_Destroy().

       Referenced by std::operator>>().

Neste exemplo podemos ver a lista de parâmetros que o método espera junto com seus respectivos tipos uma breve descrição do que cada um deles representa. Outra informação importante que recebemos é sobre as exceções que podem ser geradas. Temos a descrição do tipo de exceção gerada juntamente com a condição que cria ela.

Por fim temos uma seção para dizer onde o método foi definido, outra para listar os métodos que foram utilizados e outra com todos os métodos que dependem deste.

Extra point


Se você está disposto a acrescentar um pouco de complexidade ao seu setup para ter um pouco mais de comodidade existe o cppman que oferece uma interface terminal-friendly para a documentação online do C++.

Se deseja realizar o download da documentação para poder consultar mesmo sem internet execute: shell-session user@localhost ~/ cppman -c

Algumas vantagens de utilizar o cppman é que ele oferece syntax highlighting, exemplos de códigos e links entre páginas de documentação.


Se você gostou deste post, compartilhe com seus seguidores via twitter, e se você quiser ficar sabendo quando houverem novas publicações, me acompanhe no Twitter.