------------------------------
On Fri, Jun 27, 2014 12:15 PM BST ahi wrote:
>I am writing down the documentation as we speak I will have it ready
>by the deadline you asked for,
>but the question was not exactly the location but the content. Like
>what sort of information?
>I am asking for guidelines as to how I may explain best.
>Should I present classes and document the behavior and fields?
>I have created some wiki pages and I am adding docstrings while
>documenting components.
>
>> (1) user has a specific task to do. trying to see whether this work suits
>> his purpose. Top level readme - what exactly is this? what is it supposed to
>> do?
>> is it supposed to do what he has got in mind, or is it something completely
>> unrelated? completely irrelevant?
>>
>I have updated both README.md and README files.
>I have been reluctant to add usage examples before the tag/value
>parser was complete.
>
>As for the parser status, currently the tag/value parser is missing
>the license rules. Will continue once you are satisfied with the level
>of documentation.
Please do not find excuse to stop. It should be 'will stop once ...',
not 'will continue once...'
You really need to adjust this 'reluctance' to add examples/documentations,
as well as your 'willingness' to commit unchecked/unrunable code. To be honest,
your action and approach to those two should be swapped: start writing down
how you think it should work, with a short example (and a short accompanied
header/description saying it does not work as is just yet). Then make your
code work that way. Adjust the example on the way if it cannot be made to
work that way. When you are satisfied, removed the header. These can all be done
in the open.
You seem to think that documentation must be correct as first written, and
cannot be changed/modified/correct after, while you seem to think that it
is acceptable to write code and commit them that obviously does not run, and
fix/correct/modify later. Their roles in your head should be swapped. Docs
can change/move/refactor, code should be in incremental steps and correct
in each step - or more or less that way.
Just as you can occasionally write 'unimplemented' in code, you can write
some documentation with a side-note say "I plan to make it work this way, but
it doesn't (yet)"
I have given you two scenarios - what do YOU expect/want to see, if you are
looking for a simple parser tool as a user, or a developer pondeing whether to
adapt this code for his needs or ignore it and write his own (again)?
When was the last time you install anything by hand, extra to your distro?
What convince you that it is appropriate to your task? What alternatives have
you ignore/skip?
on somewhat unrelated/details, you could really benefit from learning 'git
rebase',
as well as git's extremely fast branching and branch-switching, and branch
merging, as well as 'git cherry-pick'. If you are worry about showing
incomplete *doc*
or other work-in-progress. (you seem to worry more about doc being incorrect,
not
worry about code being incorrect, so that's very bizarre). I have no idea why
you are
so reluctant to discuss anything, so I am guessing why you are not
performing, and guessing what is in your mind is not a good use of my time.
I would suggest putting an expanded version of the 6 lines of examples, into
say, a tools/misc/whatever sub-directory, and prepend it with '#!/usr/bin/env
python'
and append with something like:
if __name__ == '__main__':
import sys
files = sys.argv[1:]
fp = open(file, 'rb')
data = fp.read()
fp.close()
document, error = p.parse(data)
# print a few simple things out of document
And the little script should work without installing, by say, doing 'export
PYTHONPATH=./'
or something.
_______________________________________________
Spdx-tech mailing list
[email protected]
https://lists.spdx.org/mailman/listinfo/spdx-tech
