Gave some tlc to structured comments of predicates, module declarations.
authorYeGoblynQueenne@splinter <ep50@uni.brighton.ac.uk>
Tue, 30 Aug 2016 11:35:09 +0000 (14:35 +0300)
committerYeGoblynQueenne@splinter <ep50@uni.brighton.ac.uk>
Tue, 30 Aug 2016 11:35:09 +0000 (14:35 +0300)
* Still can't get structured comments to always display correctly in
  Swi documentation browser.

17 files changed:
grammar_learning/configuration.pl
grammar_learning/examples_set.pl
grammar_learning/grammar_evaluation.pl
grammar_learning/grammar_printing.pl
grammar_learning/graph_fitting.pl
grammar_learning/language.pl
grammar_learning/load_configuration.pl
grammar_learning/query_interface.pl
grammar_learning/skeleton_transformation.pl
lib/corpus_utilities.pl
lib/generate.pl
lib/grammar_utilities.pl
lib/load_libs.pl
lib/mathemagicks.pl
lib/metrics.pl
lib/project_utilities.pl
lib/term_utilities.pl

index aacc627..e19bfb0 100644 (file)
@@ -25,7 +25,6 @@
                        ]).
 
 /** <module> Configuration settings for THELEMA
-
 */
 
 % All exported predicates are also declared dynamic to allow on-the-fly
@@ -74,7 +73,7 @@ cnf_split_divisor(2).
 %
 %      Currently only used in stochastic grammar evaluation.
 %
-%      @Note: It doesn't make any sense to set this to 1 (or less) so
+%      NOTE: It doesn't make any sense to set this to 1 (or less) so
 %      instead of having to add special logic to deal with that in
 %      cross-validation predicates they throw an exception and it's as
 %      cryptic as can be, because how can I respect you if you don't
@@ -115,7 +114,7 @@ edit_sentence_frequencies(false).
 %      f_measure can be used with stochastic grammars but they are more
 %      relevant to deterministic ones.
 %
-%      @NOTE: f_measure is not implemented yet and precision_recall
+%      NOTE: f_measure is not implemented yet and precision_recall
 %      will need some tlc.
 %
 evaluation_metric(stochastic, kld).
@@ -251,11 +250,11 @@ language_file_name(ability_text).
 %        constituent of a nonterminal as a lexical parameter to the
 %        head of the latter nonterminal.
 %
-%      @NOTE: The single actually lexicalising option applies to
+%      NOTE: The single actually lexicalising option applies to
 %      deterministic right-regular grammars only. GNF grammars and
 %      stochastic grammars cannot yet be lexicalised.
 %
-%      @NOTE: Also, anything besides "none" will do- "first_nonterinal"
+%      NOTE: Also, anything besides "none" will do- "first_nonterinal"
 %      is just something descriptive. Obviously, this needs fixing.
 %
 lexicalisation_strategy(none).
@@ -267,7 +266,7 @@ lexicalisation_strategy(none).
 %      corpus. Type selects clauses according to the type of file to
 %      print.
 %
-%      TODO: this should move to project_utilities, it's grown a bit.
+%      @tbd this should move to project_utilities, it's grown a bit.
 %
 output_file_name(grammar, Path):-
        transformation_format(F)
@@ -396,7 +395,7 @@ output_file_name(compressed_corpus, corpus(Filename)):-
 %      preterminal nodes (dot explicitly prints terminals also,
 %      kind of like in a parse tree).
 %
-%      @TODO: Implement tree; complete compression.
+%      @tbd Implement tree; complete compression.
 %
 output_type(dcg).
 
@@ -432,14 +431,14 @@ output_format(skeleton_graph, '.pl').
 %      N is a number, the number of constituents of the given type on
 %      the given side.
 %
-%      @NOTE: Currently, this only makes a difference with productions
+%      NOTE: Currently, this only makes a difference with productions
 %      in Greibach Normal Form, created with:
 %      transformation_format(gnf)
 %
 %      When producing GNF grammars take care not to set options
 %      graph_arity(K), production_arity(rhs, nt, N) so that N > K.
 %
-%      @TODO: and that of course should be dealt with in the code, not
+%      @tbd and that of course should be dealt with in the code, not
 %      left up to the user.
 %
 production_arity(rhs, nt, 2).
@@ -473,14 +472,14 @@ rename_built_ins(n_).
 
 %!     sentence_completion_inference_limit_multiplier(?M) is det.
 %
-%      When deriving sentence for sentence_completion/3, stop after a
+%      When deriving sentence for sentence_completion/2, stop after a
 %      number of inferences equal to M * N, where N the length of the
 %      derivation specified by the user.
 %
 %      Since this controls inferences (including entries to the redo
 %      port) and not the depth of recursion, hhmmm..
 %
-%      @Bug: it's possible to specify a minimum value of N, at which
+%      @bug it's possible to specify a minimum value of N, at which
 %      point this multiplier will must be set to something probably
 %      unreasonably large. I think. Figure out and fix.
 %
index 654da02..3a4d977 100644 (file)
@@ -1,2 +1,5 @@
 :-module(examples_set, []).
 :-load_configuration:reconfigure.
+
+/** <module> Dummy module to allow painless examples module swapping
+*/
index 13b30de..136b6c1 100644 (file)
@@ -11,8 +11,7 @@
 :-use_module(lib(load_libs)).
 
 
-/** <module> Predicates for evaluating the performance of induced grammars.
-
+/** <module> Predicates for evaluating the performance of induced grammars
 */
 
 %!     print_k_fold_cross_validation is det.
@@ -23,7 +22,7 @@
 %      cross-validation, without tuning of parameters. The corpus,
 %      metric and the value of k are taken from the configuration.
 %
-%      @TODO: needs some tlc.
+%      @tbd needs some tlc.
 %
 print_k_fold_cross_validation:-
        configuration:evaluation_metric(stochastic,M)
@@ -229,14 +228,14 @@ original_parameters(Ps, Ps_):-
 %
 %      You've been warned.
 %
-%      @NOTE: I don't think I can really do any worse than this. This
+%      NOTE: I don't think I can really do any worse than this. This
 %      predicate has it all: runtime modification of the program by
 %      itself, destructive assignment, dynamic calls, layers upon
 %      layers of indirection... it's a mess and I can only hope I'll
 %      never have to debug it at 4 o'clock in the morning just before I
 %      need to hand all this in.
 %
-%      @TODO: incrementing parameters like we do here makes sense in
+%      @tbd incrementing parameters like we do here makes sense in
 %      our grammar induction use case but at other times we may want to
 %      train with combinations of parameters, or just with a list of
 %      them given by the user. Which means this predicate has very
@@ -366,14 +365,14 @@ reset_parameters(Ps,Ds):-
 %
 %      Results are averaged over all k-runs.
 %
-%      @NOTE: this is non-nested k-fold cross-validation, only carried
+%      NOTE: this is non-nested k-fold cross-validation, only carried
 %      out to evaluate generated grammars and report on their
 %      performance. There's no attempt to do a nested cross-validation
 %      step to tune hyperparameters, principally because there's not
 %      that many values that k (for right-regular) and j (for gnf
 %      grammars) can take.
 %
-%      @NOTE: also that if K > N, where length(Corpus, N) then you'll
+%      NOTE: also that if K > N, where length(Corpus, N) then you'll
 %      end up with some empty testing folds. This will obviously change
 %      any averagin over evaluation, so try to avoid it.
 %
@@ -433,7 +432,7 @@ average_stochastic_grammar_evaluation(T,N,Av):-
 %      Test sentences, rather than looking them up in the
 %      configuration.
 %
-%      @TODO: Since this and its 2-arity friend are copy/pasta'd,
+%      @tbd Since this and its 2-arity friend are copy/pasta'd,
 %      abstract them a bit.
 %
 stochastic_grammar_evaluation(kld, Ss, D):-
@@ -476,7 +475,7 @@ stochastic_grammar_evaluation(kld, Ss, D):-
 %      and the examples set is split into training and test sets with
 %      sizes also taken from the configuration.
 %
-%      @TODO: After fixing its 3-arity friend this needs fixing also.
+%      @tbd After fixing its 3-arity friend this needs fixing also.
 %      Problem is that Ps and Qs may end up being different lenghts at
 %      which point KLD calculation fails. But we're in a failure-driven
 %      loop so we don't notice. Dirty, inpure Prolog!
index decb7d3..5405420 100644 (file)
@@ -11,8 +11,7 @@
                             ,training_and_test_sets/2
                             ,dynamic_configuration/1]).
 
-/** <module> Predicates for printing an induced grammar.
-
+/** <module> Predicates for printing an induced grammar
 */
 
 %!     print_corpus_productions is det.
@@ -157,7 +156,7 @@ module_name(output(Filename), Module_name):-
        ,! % Backtracking to second clause raises an error
           % since there is not stream output(Filename)
        .
-% @KLUDGE
+% KLUDGE
 module_name(corpus(Filename), Module_name):-
        file_name_extension(Module_name, _Ext, Filename)
        ,!.
@@ -188,7 +187,7 @@ print_grammar_file(dcg, Grammar_module_name, Stream, S, Ps):-
 print_grammar_file(tags, Grammar_module_name, Stream, S, Ps):-
        grammar_module_exports(Ps, [], Es)
        % We don't want to print the start symbol here.
-       % @BUG
+       % Bug:
        % Hmmmrrright. But if we do it this way we miss stem-only rules like
        % ability --> [exile,target,creature]. We print those to file with
        % a new, made-up name, but they never get added to the exports.
index d3b5293..51d6bed 100644 (file)
@@ -6,12 +6,10 @@
                        ,skeleton_graph/3
                        ,graph_probabilities/2]).
 
-/* Three steps to the skeleton graph:
-1) Connect to root
-2) Add edges
-3) Add terminators
+/** <module> Predicates implementing THELEMA graph fitting component
 */
 
+
 :-use_module(lib(load_libs)).
 
 :-dynamic edge_count/3
@@ -141,7 +139,7 @@ load_skeleton_graph(M):-
 %      If the skeleton graph file is not currently loaded,
 %      unload_skeleton_graph/1 exits with a friendly message.
 %
-%      @TODO: make the not-loaded warning message an actual warning.
+%      @tbd make the not-loaded warning message an actual warning.
 %
 unload_skeleton_graph:-
        configuration:output_file_name(skeleton_graph,OF)
index 0b73db2..4f89b24 100644 (file)
@@ -5,6 +5,13 @@
                   ,nonterminal//0
                   ,e//0]).
 
+/** <module> High-level language terms.
+ *
+ * Other language modules will inherit declarations from this module,
+ * and override them to use their own start symbol etc.
+ *
+*/
+
 % Imported to allow it to see productions in language modules.
 :-use_module(lib(grammar_utilities), [productions_compressed_strings/3]).
 
index 9140370..e0184bf 100644 (file)
@@ -4,7 +4,7 @@
                             ,reconfigure/0
                             ,register_world/3]).
 
-/** <module> Load configuration settings from configuration module into the dynamic database.
+/** <module> Load configuration settings from configuration module into the dynamic database
 */
 
 %!     examples_module(?Examples_module).
@@ -47,6 +47,7 @@ reconfigure:-
                       ,E).
 
 
+
 %!     register_world(+Language_module,+Language_predicates,+Examples_module) is det.
 %
 %      Reexport Language_module renaming each predicate in the list
@@ -80,7 +81,7 @@ register_world(Language_module, Renamed_predicates, Examples_module):-
 %      just by modifying and then consulting this file (rather than
 %      having to exit).
 %
-%      @SEE register_world.
+%      @see register_world/3.
 %
 register_language(Language_module, Renamed_predicates):-
        reexport(language(Language_module), except(Renamed_predicates))
index 6f24430..9d09c6f 100644 (file)
@@ -67,7 +67,7 @@ dcg_derivation(S,L,[H|T]):-
 %
 %      Probabilities is a probability string in exponential format.
 %
-%      @NOTE: you know, the thing with these two *_derivation
+%      NOTE: you know, the thing with these two *_derivation
 %      predicates and the corresponding *_print ones is that the two
 %      groups should have the same backends and differ only in the
 %      interface they present to the user, where the *_print ones take
@@ -296,12 +296,12 @@ T = [] ;
 %      Length is a compound term with a functor in [min,max,just] and a
 %      single argument, a number. The intended use should be obvious.
 %
-%      @TODO:
+%      @tbd
 %      Answer this riddle:
 %      If the argument of Length is 0 and Sentence is not a complete
 %      sentence, sentence_completion/3 should fail? Or should it?
 %
-%      @TODO: Actually, instead of fretting with this sort of thing
+%      @tbd Actually, instead of fretting with this sort of thing
 %      start a new module, call it user_interface and go to town.
 %
 sentence_completion(G,L):-
index bb8e302..9dc48d1 100644 (file)
@@ -1,5 +1,9 @@
 :-module(skeleton_transformation, [corpus_productions/2]).
 
+/** <module> Predicates implementing graph transformation component of THELEMA
+
+*/
+
 :-use_module(lib(load_libs), except([start_symbol/1])).
 :-use_module(graph_fitting).
 
@@ -284,7 +288,7 @@ gnf_preterminals([_Vi|Vip1_Vn],Pts):-
 %      Parameterise each term in Productions with a lexical argument to
 %      produce its Lexicalised form
 %
-%      @TODO: this takes a bit of documenting. Basically, what we do is
+%      @tbd this takes a bit of documenting. Basically, what we do is
 %      look up the stack and update each reference to a production with
 %      its correct arity- if the referred production has arity n,
 %      ensure that references to it also have arity n. But need to
@@ -313,7 +317,7 @@ production_lexicalisation([P_ref,P|Ps], Temp, Acc):-
 %      Update all references to the Reference_production in the body
 %      and the head of Production so that they have the correct arity.
 %
-%      @TODO: yeah, takes a bit more documenting.
+%      @tbd yeah, takes a bit more documenting.
 %
 %lexicalised_production(P --> [T], _, P_ --> [T]):-
 %      P_ =.. [P|[epsilon]].
index 6b59708..f0f3431 100644 (file)
@@ -30,8 +30,7 @@
          ,n_gram_count/2
         ,sentence_count/2.
 
-/** <module> Predicates for tokenisation and extracting corpus statistics.
-
+/** <module> Predicates for tokenisation and extracting corpus statistics
 */
 
 %!     file_separator(?Separator) is det.
@@ -177,7 +176,7 @@ sentence_mle_output_module(M):-
 %      Use this to process input or output from other applications,
 %      particularly the Pythonic interface.
 %
-%      @NOTE: the difference of this and tokenise_line/7 or
+%      NOTE: the difference of this and tokenise_line/7 or
 %      tokenise_user_input/2 is that this doesn't read the input from a
 %      stream, duh?
 %
@@ -671,7 +670,7 @@ print_sentence_frequencies:-
 %          Examples in corpus
 %      ==
 %
-%      @TODO: this, along with several of the counting predicates in
+%      @tbd this, along with several of the counting predicates in
 %      this module, can go significantly faster by use of the
 %      library(aggregate) predicates, particularly aggregate/4 with the
 %      "count" template.
@@ -803,7 +802,7 @@ write_n_gram_model_term(S, T):-
 %      See Jurafsky and Martin (2009), Charniak, Manning and Schuze and
 %      others for the theory.
 %
-%      @NOTE: This will calculate the relative frequency of unigrams as
+%      NOTE: This will calculate the relative frequency of unigrams as
 %      "1". This may not be ideal. Think about changing it. In any case
 %      that may be a bit of a silly use-case so maybe it doesn't really
 %      matter.
index 594ec12..ec2008d 100644 (file)
@@ -2,7 +2,7 @@
                   ,rule_name/1]).
 
 
-/** <module> Predicates used to generate terms, lists, strings etc.
+/** <module> Predicates used to generate terms, lists, strings etc
 
 */
 
index ffc02fd..15741e8 100644 (file)
@@ -9,7 +9,7 @@
 :-use_module(mathemagicks).
 
 
-/** <module> Yet another DCG processing module.
+/** <module> Yet another DCG processing module
 
 */
 
@@ -264,7 +264,7 @@ prolog_dcg(Head:-Body, DCG):-
 %      possibility of the body containing a pushback list that might
 %      superficially look like a list of terminals.
 %
-%      @NOTES_TO_SELF:
+%      NOTES_TO_SELF:
 %
 %      Meh. Never mind, this will not work with rules with arity 1 or
 %      more. Need to rethink.
@@ -289,7 +289,7 @@ prolog_dcg(Head:-Body, DCG):-
 %      prolog_dcg/4, that matches their different configurations to
 %      disambiguate the pushbacks from the terminals.
 %
-%      @TODO: It's possible all this can be done much more neatly with
+%      @tbd It's possible all this can be done much more neatly with
 %      a better production_term//1 grammar.
 %
 prolog_dcg(Name, [], Head_args, [[]], Name --> Head_diff):-
index c5c66ef..50c3472 100644 (file)
@@ -1,12 +1,15 @@
 :-module(load_libs, []).
 
-/** <module> Load module, used to load and reexport utilities modules so that client modules only have to import this one.
+/** <module> Load module, used to load and reexport utilities modules
 
-Modules in this directory however should still call one another by
-their actual name, to reduce indirection (a.k.a. potential confusion).
-Think of the modules in this directory as a sort of self-contained
-library, spread over a few different source files but presenting a
-unified interface to modules outside the library.
+  This way, client modules only have to import this module to make use
+  of those modules.
+
+  Modules in this directory however should still call one another by
+  their actual name, to reduce indirection (a.k.a. potential confusion).
+  Think of the modules in this directory as a sort of self-contained
+  library, spread over a few different source files but presenting a
+  unified interface to modules outside the library.
 */
 
 :-reexport(project_utilities).
index 3f13cee..2db79f4 100644 (file)
@@ -4,7 +4,7 @@
                       ,product_of/3
                       ,sum_of/3]).
 
-/** <module> Predicates for arithmetic calculations etc.
+/** <module> Predicates for arithmetic calculations etc
 
 */
 
index 6b17529..26eb3f2 100644 (file)
@@ -3,7 +3,7 @@
 :-use_module(mathemagicks).
 :-use_module(lib(load_libs)).
 
-/** <module> Predicates to measure the performance of models and algorithms.
+/** <module> Predicates to measure the performance of models and algorithms
 */
 
 
index 13db5c4..741dff5 100644 (file)
@@ -32,7 +32,7 @@
 :-use_module(grammar_utilities).
 :-use_module(corpus_utilities).
 
-/** <module> Miscellanneous utility predicates used across the project.
+/** <module> Miscellanneous utility predicates used across the project
 */
 
 
@@ -422,7 +422,7 @@ sample_(without_replacement,Ds,_N*S,Ss_):-
 %      selected for inclusion in Sample. The list of numbers may
 %      contain duplicates to allow replacement.
 %
-%      @TODO: this and unique_sample/3 could probably be one predicate.
+%      @tbd this and unique_sample/3 could probably be one predicate.
 %      Additionally, it could incorporate the double-accumulation of
 %      splits/4.
 %
@@ -514,7 +514,7 @@ start_symbol(S):-
 %      parent to use call_with_inference_limit/3 to limit depth of
 %      derivations.
 %
-%      @TODO: now this is exported in its own right, it needs better
+%      @tbd now this is exported in its own right, it needs better
 %      dox. Do it.
 %
 sentence_completion(G,S,L,S_):-
@@ -889,7 +889,7 @@ examples_corpus(Examples):-
 %
 %      The number of all unique examples in the examples corpus.
 %
-%      @TODO: this currently only counts examples in the first
+%      @tbd this currently only counts examples in the first
 %      configured module. Implement the "(s)" (though you'll have to
 %      do that application-wide, nothing else can handle mulitple
 %      examples modules right now).
index dfb9a17..f5b83cb 100644 (file)
@@ -19,7 +19,7 @@
                         ,tree_list/2\r
                         ]).\r
 \r
-/** <module> Utility predicates for analysing, constructing and printing compound terms, including lists.\r
+/** <module> Utility predicates for analysing, constructing and printing compound terms, including lists\r
 \r
 */\r
 \r