Comments / documentation #2

New Issue

c.jansen · 2021-11-29T13:46:12Z

c.jansen commented

2021-11-29 13:46:12 +00:00

Suggesties voor duidelijkere documentatie:

Documentatie van de code (in de code zelf) bestaat nu voornamelijk uit een korte beschrijving welke handeling een functie verricht. Wat ontbreekt is:

Het grotere plaatje: hoe zijn functies met elkaar verbonden? Hoe wordt data langs verschillende functies gestuurd? Maar ook: een korte omschrijving van alle functies binnen een grote class.
De interface van functies: beschrijving van args en returns: datatype, afmetingen array, betekenis, eenheid. Bijv. lasp/filter/soundpressureweighting.py/class SPLFilterDesigner/def A_Sos_design(), r. 148-167: deze functie geeft second order sections waarmee je een A-weging kan toepassen. Maar wat stellen ze precies voor? Moet je dit op een tijdssignaal toepassen, magnitude spectrum, power spectrum of power spectrum in dB?
Beschrijving hoe de functie werkt. Bijv. lasp/filter/soundpressureweighting.py/class SPLFilterDesigner, r. 17-34 kan ik niet volgen. Met een verwijzing naar IEC/CD 1672 is het duidelijk.
Uitleg naamgeving functies / variabelen. Ik zie dat er soms een systeem in zit dat nu wordt gebruikt in plaats van documentatie, alleen zie ik het systeem soms niet.

Suggesties voor duidelijkere documentatie: Documentatie van de code (in de code zelf) bestaat nu voornamelijk uit een korte beschrijving *welke handeling* een functie verricht. Wat ontbreekt is: - Het grotere plaatje: hoe zijn functies met elkaar verbonden? Hoe wordt data langs verschillende functies gestuurd? Maar ook: een korte omschrijving van alle functies binnen een grote class. - De interface van functies: beschrijving van args en returns: datatype, afmetingen array, betekenis, eenheid. Bijv. `lasp/filter/soundpressureweighting.py/class SPLFilterDesigner/def A_Sos_design(), r. 148-167`: deze functie geeft second order sections waarmee je een A-weging kan toepassen. Maar wat stellen ze precies voor? Moet je dit op een tijdssignaal toepassen, magnitude spectrum, power spectrum of power spectrum in dB? - Beschrijving *hoe* de functie werkt. Bijv. `lasp/filter/soundpressureweighting.py/class SPLFilterDesigner, r. 17-34` kan ik niet volgen. Met een verwijzing naar IEC/CD 1672 is het duidelijk. - Uitleg naamgeving functies / variabelen. Ik zie dat er soms een systeem in zit dat nu wordt gebruikt in plaats van documentatie, alleen zie ik het systeem soms niet.

c.jansen added the

doc

label 2022-11-08 12:38:35 +00:00

c.jansen commented

2022-11-08 12:43:46 +00:00

Het zou erg helpen als er een tekstbestandje is met welke scripts welke functies bevatten. Dat scheelt een hoop zoekwerk. "Go to definition" in de IDE werkt niet i.v.m. deels C++.