JuliaLang/julia

Show similar functions in docstrings

Open

#23.763 aberto em 19 de set. de 2017

Ver no GitHub
 (3 comments) (3 reactions) (0 assignees)Julia (5.773 forks)batch import
docsgood first issuehelp wanted

Métricas do repositório

Stars
 (48.709 stars)
Métricas de merge de PR
 (Mesclagem média 20d 6h) (157 fundiu PRs em 30d)

Description

I think discoverability would be greatly enhanced, if there would be some hints at similar functions in the docstrings. I imagine a line of See also: ...function names... which should be generated from a table of related functions automatically.

This came to my mind when looking at the docs of pop!. The functions shift! and splice! offer solutions to similar problems, but their names cannot be guessed from each other.

pop!(collection, key[, default])

  Delete and return the mapping for key if it exists in collection, otherwise return default, or
  throw an error if default is not specified.

[...]

See also: shift!(), splice!()

Of course, the wording is open for bike shedding 👍

Guia do colaborador

Direção de pesquisa
A questão solicita a adição de uma linha 'Veja também' nas strings de documentação, vinculando a funções semelhantes como shift! e splice!. Para implementar, é necessário identificar onde as strings de documentação são geradas na biblioteca base do Julia, provavelmente no módulo 'Base'. Investigue o código existente de geração de documentação em arquivos como 'base/docs.jl' ou similares. A proposta é criar uma tabela de funções relacionadas e incluir referências automaticamente. A implementação pode envolver a modificação do sistema de documentação para ler um mapeamento e anexar referências cruzadas. Nenhuma resposta do mantenedor é visível, mas a ideia é direta. Comece examinando como as strings de documentação atuais são produzidas e encontre onde inserir a nova linha.
Pilha de tecnologia
None
Domain
documentation
Tipo Issue
Funcionalidade
DifficultyDificuldade de implementação estimada para um novo contribuidor, de 1 para alterações muito pequenas a 5 para trabalho de nível especializado.
2
Tempo estimadoUm intervalo de tempo aproximado para um colaborador experiente investigar, implementar, testar e preparar um pull request.
1-2 dias
Status da atividadeQuão disponível o issue aparece agora: novo, ativo, obsoleto, bloqueado ou aguardando entrada do mantenedor.
Recente
ClarityCom que clareza o issue explica a mudança esperada, os critérios de aceitação e a próxima etapa.
Principalmente claro
Prerequisites
None
Simpatia para novatosUma pontuação de 1 a 100 que estima o quão acessível este issue é para colaboradores iniciantes.
65