Faraday: Solicitação de recurso: defs de método explícito para verbos HTTP

Olá @dduugg , em vez de definir explicitamente os métodos, gostaria de explorar uma solução amigável para documentação.
Também usamos a definição de meta-programação na conexão: https://github.com/lostisland/faraday/blob/master/lib/faraday/connection.rb#L195

Isso funciona bem com os pontos que você mencionou acima?
Nesse caso, poderíamos replicar um trecho de documentação semelhante para o módulo Faraday também.

Olá @iMacTia , obrigado pela resposta. Não acho que o problema seja resolvido com documentação. Eu poderia incomodá-lo a elaborar sobre a resistência a definições explícitas? Acho que seria melhor enquadrar a discussão. Por exemplo, uma abordagem de documentação é provavelmente tão detalhada (contando várias diretivas @!method & @!scope , além do código method_missing ) do que as sete defs de encaminhamento explícito de uma linha Estou sugerindo Faraday . Mas não sei se esse é o motivo aqui (o código é lido muito mais do que escrito, então acho que otimizar para o escritor do código é um erro de qualquer maneira).

Existem basicamente 2 pontos que me colocam em risco com essa mudança.

• Pessoalmente, não acho que usar delegates seja uma vantagem apenas para o criador do código. Uso Ruby há anos e, como outros, passei a apreciar a sintaxe sucinta dessa linguagem. Quando leio algum código e encontro delegates , imediatamente sei o que isso significa e pode condensar potencialmente dezenas de linhas de código em apenas algumas delas.
• Proxies de verbos HTTP não são a única instância em Faraday em que aproveitamos a metaprogramação, há muitas outras instâncias, que provavelmente sofrem do mesmo problema que você levantou aqui, mas ainda não foram notadas. Concordar com essa mudança abrirá uma exceção ou criará um precedente, coisas que eu gostaria de evitar.

Mas, em vez de me concentrar em minha resistência a essa mudança, prefiro discutir sobre que tipo de vantagens estamos tentando apresentar aqui. Eu entendo perfeitamente o problema que você está descrevendo e realmente acho que devemos tentar resolvê-lo, se possível!
Portanto, se o principal problema aqui é a compatibilidade com IDEs / ferramentas para sugestões de código, preenchimento automático e documentação, então estou simplesmente propondo encontrar uma solução alternativa como comentários de documentação (já usamos o YARD bastante).
E você também está certo quando diz que essa solução é tão prolixa, embora eu argumente que um comentário não afetará a legibilidade tanto quanto uma lista de métodos e é facilmente reconhecível.

Olá @iMacTia , obrigado pela sua resposta. Mudamos para uma biblioteca diferente com melhor capacidade de descoberta de API e suporte a ferramentas, mas compartilharei minhas idéias caso você as considere úteis.

• A capacidade de descoberta não impede o uso de metaprogramação (embora, neste caso específico, eu ache que def s explícitos são o caminho a percorrer), mas exigiria a substituição da abordagem method_missing , conforme descrito anteriormente.
• Não tenho certeza se entendi o argumento delegates . Faraday não parece usar delegadores explícitos ao lidar com métodos de verbos HTTP. (A confusão neste ponto é provavelmente um cheiro de código de que a implementação de métodos de verbo HTTP é excessivamente complicada).
• Teremos que concordar em discordar de que delegate e similares são uma ajuda para o redator do código. Estou trabalhando com pessoas com algumas décadas de experiência coletiva em ruby ​​e não encontramos nenhum benefício de legibilidade para a abordagem aqui (mesmo descontando o tempo perdido tentando explorar a API via pry, YARD, sorbet e solargraph ) Pode valer a pena assistir a uma tentativa de rubista de explorar esta API pela primeira vez, pelo menos neste ponto específico.

Estou apenas tentando fornecer algum feedback honesto (e, espero, útil) aqui. Ainda agradeço o tempo e o esforço dedicados a essa contribuição para o OSS.

Ei, obrigado por todo o seu trabalho árduo em Faraday! Eu sei que este é um problema antigo, mas tendo a concordar que a descoberta é um pouco problemática. Estou trabalhando em algum middleware e adicionei esta seção ao meu README. Minha biblioteca é voltada para alguém que talvez não tenha usado Faraday antes, então cabe a mim explicar as coisas. Direi (um tanto hesitante) que não foi fácil decifrar as coisas.

@gurgeous Concordo que a documentação é definitivamente uma frente em que poderíamos estar fazendo um trabalho melhor (embora tenhamos começado a lidar com isso lançando o site Faraday ), mas não vejo como a sugestão desta edição resolverá seu ponto específico.

Talvez eu esteja perdendo o ponto porque simplesmente estou acostumado a trabalhar de uma maneira diferente, mas se não sei como usar uma biblioteca, não confio no preenchimento automático e adivinhação para saber o que fazer.
Em vez disso, verifico a documentação da biblioteca e, se isso não ajudar, mergulho no código para ver como funciona.

Daí porque eu acho que uma documentação melhorada (visual ou no código) é a maneira de resolver isso.
Mas talvez eu esteja faltando alguma coisa aqui ou um caso de uso específico em que uma documentação melhor não ajudaria?
Meu entendimento de "descoberta" está correto?

Meu entendimento de "descoberta" está correto?

Não no meu caso. Minha expectativa era poder fazer ls Faraday em pry , seguido por $ Faraday.get , etc. se eu quisesse mergulhar em um método específico. Eu sinto que fui capaz de fazer isso efetivamente com qualquer outra gema que usei, raramente (ou nunca) precisando navegar para uma página de documentação, portanto, abrindo este tíquete. (Isso é além de outros problemas mencionados acima, como ferramentas de análise estática que não reconhecem o código que usa a biblioteca.)

Obrigado novamente por nos ouvir.

Eu amo o site Faraday! Talvez eu possa enviar um PR com algumas sugestões? Fico feliz em ajudar. Acho que esse tipo de esforço sempre compensa para os recém-chegados. Deixe-me saber se você estiver interessado.

Em termos de pry + ls Faraday , eu também sou um fã desse padrão e o utilizo extensivamente. Afastar-se de method_missing não é uma má ideia. Ruby está lentamente sendo puxado nessa direção com a ascensão do Ruby 3, servidores de linguagem, RBS, etc. Eu acho que isso é secundário para documentos, no entanto.

@gurgeous Estamos _estando_ interessados ​​na documentação Pull Requests, encontre o diretório docs/ com um conjunto de Gemfile (e README) que é usado para publicar o site nas páginas do GitHub, que estamos usando. Se o seu uso não for claro, o processo de atualização do site, abra um problema ou um PR para _that_, também.

Obrigado por se preocupar com os usuários Faraday!

Eu amo o site Faraday! Talvez eu possa enviar um PR com algumas sugestões? Fico feliz em ajudar. Acho que esse tipo de esforço sempre compensa para os recém-chegados. Deixe-me saber se você estiver interessado.

@gurgeous absolutamente! Sempre recebemos ajuda para melhorar a documentação ou o site da Web, pois coisas que são óbvias para nós, mantenedores, podem não ser tão óbvias para os usuários. Além disso, nós realmente lutamos com o tempo e isso geralmente tem um custo para a documentação. Na verdade, a documentação estaria em um estado muito pior se não fosse por @olleolleolle continuou esforços 😄!

No ponto pry (cc @dduugg), nunca usei, por isso provavelmente não estava entendendo.
Eu apenas experimentei com seus detalhes adicionais e percebi que ls Faraday::Connection mostra os métodos gerados dinamicamente, bem como os delegados 🙌.
Então, meu entendimento original de que não podemos usar esse tipo de "mágica" do Ruby estava errado, e realmente o único limite é usar missing_method .

O que eu não gostava muito era a introdução de métodos explícitos como os seguintes:

def self.get(...)
  ...
end

def self.post(...)
  ...
end

# ... and so on ...

Mas se pudermos consertar a descoberta de pry adicionando definições dinâmicas ou delegações ao módulo Faraday , então isso é algo que eu concordaria. Desculpe por não ter entendido da primeira vez!

Não se preocupe com as restrições de tempo. Nunca se sinta mal por ser um mantenedor de código aberto! Agradecemos seus esforços de qualquer maneira. Eu estive lá também ...

Vou iniciar uma discussão re: docs para ter certeza de que estamos na mesma página.

@iMacTia Como um usuário saberia como olhar para Faraday::Connection ? Desde então, mudei para uma gema HTTP com uma API detectável, mas dei uma olhada rápida em https://lostisland.github.io/faraday/usage/ e nenhum dos exemplos de código a usa explicitamente (embora o último o faça implicitamente). A maioria dos exemplos invoca métodos estáticos em Faraday , mas eles não são encontrados em pry. Não conheço nenhuma outra joia que tenha adotado essa abordagem, e ainda considero que é um antipadrão.

Obrigado, como sempre, por me ouvir.