These are just comments, feel free to disregard.
- While the Python document system used
```
as a tag for locating source code in the documentation, I think it would be better to make use of the current PlDoc system of @Tag for locating examples. Since no existing tag works for the needs of example code, new tag(s) should be created.
The current PlDoc tags are only for one line or word, but source code needs multiple lines, need bookend type tags, e.g. @example_start
, and @example_end
% ```example
% ?- my_sort([4,3,1,2], Sorted),
% Sorted = [1, 2, 3, 4].
% ```
would be added to the Prolog documentation as
% @example_start
% ?- my_sort([4,3,1,2], Sorted),
% Sorted = [1, 2, 3, 4].
% @example_end
- Since part of the need is to validate the example code, it should use the existing SWI-Prolog unit test.
% @example_start
% ?- my_sort([4,3,1,2], Sorted),
% Sorted = [1, 2, 3, 4].
% @example_end
should be
% @example_start
% :- begin_tests(my_sort).
%
% test_001_test_case([4,3,1,2],[1,2,3,4]).
% test(001, [forall(test_001_test_case(Input,Expected_result))] ) :-
% my_sort(Input,Result),
% assertion( Result == Expected_result).
%
% :- end_tests(my_sort).
% @example_end
- While the industry standard is to write one test with a verbose description per test, IMHO what works better is seeing all of the test cases lined up for quick comparison.
% @example_start
% :- begin_tests(my_sort).
%
% test_001_test_case([],[]).
% test_001_test_case([1],[1]).
% test_001_test_case([1,2],[1,2]).
% test_001_test_case([2,1],[1,2]).
% test_001_test_case([1,2,3],[1,2,3]).
% test_001_test_case([1,3,2],[1,2,3]).
% test_001_test_case([2,3,1],[1,2,3]).
% test_001_test_case([2,1,3],[1,2,3]).
% test_001_test_case([3,1,2],[1,2,3]).
% test_001_test_case([3,2,1],[1,2,3]).
%
% test_001_test_case([a],[a]).
% test_001_test_case([a,b],[a,b]).
% test_001_test_case([b,a],[a,b]).
% test_001_test_case([a,b,c],[a,b,c]).
% test_001_test_case([a,c,b],[a,b,c]).
% test_001_test_case([b,c,a],[a,b,c]).
% test_001_test_case([b,a,c],[a,b,c]).
% test_001_test_case([c,a,b],[a,b,c]).
% test_001_test_case([c,b,a],[a,b,c]).
%
% test(001, [forall(test_001_test_case(Input,Expected_result))] ) :-
% my_sort(Input,Result),
% assertion( Result == Expected_result).
%
% :- end_tests(my_sort).
% @example_end
-
Now that there are too many tests and another purpose of this is to help others learn, should some of the tests be shown and some of the test run without being shown? Should a user be able to choose which test to run? I think the idea of converting the example code into a SWISH console would work better.
-
If the concept of grabbing the code from HTML and putting into a SWISH console is used, then maybe extending PlDoc with tags is the wrong way to code and instead modify PlDoc to create HTML tags friendly to the lpn-swish-proxy