JuliaLang/julia

Show similar functions in docstrings

Open

#23.763 aperta il 19 set 2017

Vedi su GitHub
 (3 commenti) (3 reazioni) (0 assegnatari)Julia (5773 fork)batch import
docsgood first issuehelp wanted

Metriche repository

Star
 (48.709 star)
Metriche merge PR
 (Merge medio 20g 6h) (157 PR mergiate in 30 g)

Descrizione

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 👍

Guida contributor

Direzione di ricerca
La richiesta prevede l'aggiunta di una riga 'Vedi anche' nelle stringhe di documentazione, per collegare funzioni simili come shift! e splice!. Per implementarla, è necessario identificare dove vengono generate le stringhe di documentazione nella libreria base di Julia, probabilmente nel modulo 'Base'. Indagare il codice esistente di generazione della documentazione in file come 'base/docs.jl' o simili. La proposta è di creare una tabella di funzioni correlate e includere automaticamente i riferimenti. L'implementazione potrebbe comportare la modifica del sistema di documentazione per leggere una mappatura e aggiungere riferimenti incrociati. Non è visibile alcuna risposta da parte dei manutentori, ma l'idea è semplice. Iniziare esaminando come vengono prodotte le attuali stringhe di documentazione e trovare dove inserire la nuova riga.
Tech stack
Nessuno
Dominio
documentation
Tipo issue
Funzionalità
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
1-2 giorni
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Nuova
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Abbastanza chiara
Prerequisiti
Nessuno
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
65