declt
declt copied to clipboard
didierverna
Allow renaming of Conclusion node
Perhaps naming of the Conclusion node should be user configurable. For example one might wish this section to be named "Change Log". One way to do this would be to set the name by a variable in the code for this node. Happy to help with this change if someone has a bit of guidance in how they would like it done.
I have to think about this. Maybe we want something more general, like a way of providing additional sections, either at the start or at the end of the manual.
Perhaps this could be solve in the way some of the other systems do it: look for comments at 'file level', e.g. ;;;; and include those into the documentation. This would also allow something more than just a conclusion, relevant comments could be included anywhere in the documents.
I agree that the current intro / conclusion feature is limited. Soon, Declt will replace Quickref in using README files as default contents for an introduction. I'm reluctant to provide hacks for perverting their original use to something else. For ChangeLogs for example, a better solution would be to detect ChangeLog files and use their contents in a specific section.
I'm also reluctant to turn Declt into a litterate programming thingy. In the case of file-wide comments, there's always the :description and :long-description options in the ASDF file, and they are already handled. It's just that nobody uses them for anything else than the system itself probably.
One thing I've had in mind for quite some time now (but that's not the job of Declt) is to have a reader macro of some sort which grabs a string and dynamically uses it to fill the relevant :long-description slot for the corresponding file. That way, the .asd can remain concise, and the global file comment stays in the file itself.
I was also thinking of reader macro's for file level comments. I can see why you'd be reluctant to turn Declt into a literate programming system, but I think there may a need for one. MGL-PAX seems to do a good job, but introduces a run-time dependency. I'm trying to think of how you might avoid this and not introduce a code-walker.
I'd like to see how far the Declt design philosophy can go first though. One problem is in knowing what documentation was missed. Can the system generate a report saying: 'Hey, you defined slot X in class Y, but I didn't find any :documentation for it. As it is now the user has to scour through the code looking for things that he perhaps should have documented, but didn't. Can SBCL's 'notes' be made to do this?
One suggestion: perhaps turn on 'discussion' in this repo for discussions like this. That way the information doesn't get lost in an issue.
This idea of reporting missing documentation is very interesting and probably straightforward to implement with the condition system. In fact, there are already two cases in which Declt issues a warning about a spotted oddity in the code it asses: when it finds a short form method combination without a defined operator, and when it finds a short form setf expander without a writer function. This can surely be turned into a full blown analysis and reporting system. I'll write this down because I like the idea a lot.
I don't know what discussions are but I'll figure it out and activate the feature.
I don't know what discussions are but I'll figure it out and activate the feature.
Done.