Introduction Reports Analysis Discoveries
Conclusion
The Quickref Cohort
e ELS 2024 E
Didier Verna
EPITA / LRDE
didier@lrde.epita.fr
lrde/~didier
@didierverna didier.verna
in/didierverna
Introduction Reports Analysis Discoveries
Conclusion
Preamble
What is a “cohort” ?
A group of individuals having a statistical factor (such
as age or class membership) in common in a
demographic study.
– The Meriam-Webster Dictionary
a
, denition 2.b.
a
https://www.merriam-webster.com/dictionary/cohort
The Quickref Cohort / ELS 2024 – Didier Verna 2/20
Introduction Reports Analysis Discoveries
Conclusion
History
I
2010: Declt project starts
I
reference manual generator for
Common Lisp libraries
I
2013: First stable release
I
2017: Quickref project starts
I
Declt (2.3) wrapper for the
whole Quicklisp world
I
Today: more than 2000 libraries
documented
The Quickref Cohort / ELS 2024 – Didier Verna 3/20
Introduction Reports Analysis Discoveries
Conclusion
Pressure Points
1. Quickref runs Declt in separate processes (cf. ELS 2019)
I
Library information not directly available
I
Author index not straightforward to build
⇒ Author information extracted in an ad hoc way
2. Declt generates Texinfo les
I
Subsequent rendering in PDF, HTML, etc.
I
But people want other formats or direct HTML output
⇒ Incentive to design an abstract representation
The Quickref Cohort / ELS 2024 – Didier Verna 4/20
Introduction Reports Analysis Discoveries
Conclusion
The Declt Pipeline (ongoing)
Current state: stage 1 complete (Decl 4.0b1)
System
Assessment
Assembly
Typesetting
Manual
report
(declt system ...)
(assess system ...)
(declt-1 report ...)
1. Assessment stage: library −→ report
I
Collected (cross-referenced) information, unordered
2. Assembly stage: report −→ script
I
Organized content, format-independent
3. Typesetting stage: script −→ manual
I
Formatted reference manual
The Quickref Cohort / ELS 2024 – Didier Verna 5/20
Introduction Reports Analysis Discoveries
Conclusion
Consequences
I
Author index much easier to generate
1. (declt:assses library) −→ report
2. Extract author information from report
3. Continue with (declt-1 report)
And a new idea…
What if we dumped all Quicklisp library
reports to les, and used them for other
purposes than documentation ?
I
A cohort of more than half a million programmatic denitions!
The Quickref Cohort / ELS 2024 – Didier Verna 6/20
Introduction Reports Analysis Discoveries
Conclusion
Plan
Declt Reports
Cohort Analysis
Funny discoveries
The Quickref Cohort / ELS 2024 – Didier Verna 7/20
Introduction Reports Analysis Discoveries
Conclusion
Declt Reports
#<DECLT.ASSESS:REPORT {70069BE4D3}>
--------------------
Class: #<STANDARD-CLASS DECLT.ASSESS:REPORT>
--------------------
Group slots by inheritance [ ]
Sort slots alphabetically [X]
All Slots:
[ ] CONTACTS = (("Didier Verna" . "didier@didierverna.net"))
[ ] COPYRIGHT-YEARS = "2010-2013, 2015-2022"
[ ] DEFINITIONS = (#<DECLT.ASSESS:SYSTEM-DEFINITION declt.core>
#<DECLT.ASSESS:MODULE-DEFINITION src>
...)
[ ] LIBRARY-NAME = "Declt"
[ ] LIBRARY-VERSION = "4.0 beta 2 \"William Riker\""
[ ] LICENSE = (:BSD "The BSD License" "Permission to use, ...)
[ ] SYSTEM-NAME = "net.didierverna.declt"
[ ] TAGLINE = "Documentation Extractor from Common Lisp to Texinfo"
The Quickref Cohort / ELS 2024 – Didier Verna 8/20
Introduction Reports Analysis Discoveries
Conclusion
Denitions Hierarchy (excerpt)
denition
symbol
ASDF
package
funcoid
varoids classoids
setfable funcoids
methods
method combinations
compiler macros
types
setf expanders
The Quickref Cohort / ELS 2024 – Didier Verna 9/20
Introduction Reports Analysis Discoveries
Conclusion
Example: Generic Function Denition
#<DECLT.ASSESS:GENERIC-FUNCTION-DEFINITION {70060D9653}>
--------------------
Class: #<STANDARD-CLASS DECLT.ASSESS:GENERIC-FUNCTION-DEFINITION>
--------------------
Group slots by inheritance [ ]
Sort slots alphabetically [X]
All Slots:
[ ] COMBINATION = #<DECLT.ASSESS:COMBINATION-DEFINITION STANDARD>
[ ] EXPANDER-FOR = NIL
[ ] EXPANDERS-TO = NIL
[ ] FOREIGN = NIL
[ ] HOME-PACKAGE = #<DECLT.ASSESS:PACKAGE-DEFINITION DECLT.ASSESS>
[ ] METHODS = (#<DECLT.ASSESS:METHOD-DEFINITION VALUE-TYPE> ...)
[ ] OBJECT = #<STANDARD-GENERIC-FUNCTION DECLT.ASSESS:VALUE-TYPE (2)>
[ ] SETF = NIL
[ ] SOURCE-FILE = #<DECLT.ASSESS:LISP-FILE-DEFINITION symbol>
[ ] SYMBOL = DECLT.ASSESS:VALUE-TYPE
[ ] UID = 51
The Quickref Cohort / ELS 2024 – Didier Verna 10/20
Introduction Reports Analysis Discoveries
Conclusion
Records Dumping (beta!)
("net.didierverna.declt"
(:CONTACTS 1)
...
(:SYSTEM "net.didierverna.declt.assess"
:DOCSTRING 44 :DEPENDENCIES 2 :CHILDREN 2
:DEFSYSTEM-DEPENDENCIES 0)
...
(:PACKAGE "NET.DIDIERVERNA.DECLT.ASSESS"
:DOCSTRING 39
:EXTERNAL-SYMBOLS 169 :INTERNAL-SYMBOLS 119
:USE-LIST 2 :USED-BY-LIST 1)
...
(:CLASS "GENERIC-FUNCTION-DEFINITION"
:DOCSTRING 154
:DIRECT-SUPERCLASSES 1 :DIRECT-SUBCLASSES 1
:DIRECT-METHODS 11
:DIRECT-SLOTS 3)
...
(:GENERIC-FUNCTION "DOCUMENT"
:DOCSTRING 45 :MEHTODS 39)
...)
The Quickref Cohort / ELS 2024 – Didier Verna 11/20
Introduction Reports Analysis Discoveries
Conclusion
Plan
Declt Reports
Cohort Analysis
Funny discoveries
The Quickref Cohort / ELS 2024 – Didier Verna 12/20
Introduction Reports Analysis Discoveries
Conclusion
Symbols
0
5000
10000
15000
20000
25000
0 5 101520253035404550556065707580859095100105110115120125130135
Symbol Names Lengths
Symbols number
Symbol name length
The Quickref Cohort / ELS 2024 – Didier Verna 13/20
Introduction Reports Analysis Discoveries
Conclusion
Documentation
0
20
40
60
80
100
Documentation percentages
Constant
Special
Ordinary Function
Macro
Generic Function
Method
Method Combination
Class
Slot
Condition
Setf Expander
Compiler Macro
Type
Documented denitions percentage
Programmatic denitions
The Quickref Cohort / ELS 2024 – Didier Verna 14/20
Introduction Reports Analysis Discoveries
Conclusion
Classloids
0
1
2
3
4
5
6
7
8
Structures Classes Conditions
Slots
Methods
Parents
Children
Slots
Methods
Parents
Children
Slots
Methods
Parents
Children
Average number of direct ...
The Quickref Cohort / ELS 2024 – Didier Verna 15/20
Introduction Reports Analysis Discoveries
Conclusion
Plan
Declt Reports
Cohort Analysis
Funny discoveries
The Quickref Cohort / ELS 2024 – Didier Verna 16/20
Introduction Reports Analysis Discoveries
Conclusion
Docstring Length Record
I
For a macro
I
27253 characters / 550 lines
I
Hand written – In fact, a complete user manual
I
DEFBINARY
I
lisp-binary / Jeremy Phelps
The Quickref Cohort / ELS 2024 – Didier Verna 17/20
Introduction Reports Analysis Discoveries
Conclusion
Symbol Length Record
I
A function name
I
135 characters
I
FORMAT’ed & INTERN’ed
I
|semantic-checker for character class with clauses ((#\\0 #\\9) (#\\a #\\f)(#\\A #\\F)) |
I
ESRAP-PEG / Michael Raskin
The Quickref Cohort / ELS 2024 – Didier Verna 18/20
Introduction Reports Analysis Discoveries
Conclusion
Symbol Cardinality Record
I
A class name
I
13 components (incl. 3 empty ones)
I
Hand written
I
ARC-CONSTRAINT-TANGENT-TO--CENTER-ON--THROUGH-POINT--SELECT-SIDE
I
Gendl / Dave Cooper
The Quickref Cohort / ELS 2024 – Didier Verna 19/20
Introduction Reports Analysis Discoveries
Conclusion
Conclusion
I
More than half a million ASDF / programmatic entities available
I
Tarball & Sample statistical charts available
https://quickref.common-lisp.net/cohort/
I
Updated along with the Quickref documentation
I
Please advise: serialization
Can drop original objects, but…
I
need to aintain cross-references between denitions
I
potential problems with lambda-lists, EQL-specializers, etc.
The Quickref Cohort / ELS 2024 – Didier Verna 20/20