add preliminary versions of documentation #25
Conversation
josesimoes
commented
Dec 28, 2016
josesimoes
commented
- add folder structure for documentation
- add main documents for project
| Area (A). | ||
|
|
||
| Note: If you don't find the area in the below list, or you have a general | ||
| question, send a message to Stanislav Simicek (@cw2) and Richard Lander |
There was a problem hiding this comment.
Thanks.
IMHO the wiki is a better place for the coding style documents.
Regarding the CMake documentation, please leave it in the cmake branch where it belongs - it will be merged along with the source code.
The Documentation folder should be changed to 'docs' - because it can be set as the source of github pages if needed.
|
|
||
| This document describes how to debug **nano Framework** native code using VS Code. | ||
|
|
||
| <a name="Prerequisites"></a> |
There was a problem hiding this comment.
I think it is not necessary to have explicit anchor tags - it seems github markdown renderer generates them automatically (e.g. see the root README - when you hover over a heading, there is a link icon shown next to it).
There was a problem hiding this comment.
It looks like is that way. I was in doubt about the titles with spaces but I've figured it now.
| Here's what you probably need to change in order to adapt this file to your setup. | ||
| - miDebuggerPath: full path to the gdb executable (this one is inside the GCC toolchain folder) | ||
| - program: full path to the .hex or .bin output file that results from a successful build | ||
| - setupCommands (third ‘text’ entry): full path to the final image (same as above) |
There was a problem hiding this comment.
Nitpick: prefer regular apostrophe ' (0x27)
There was a problem hiding this comment.
And it should be that one... I guessed it got replaced by a different char when I copy/paste from my blog article...
|
|
||
| 1. We use [Allman style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces, where each brace begins on a new line. A single line statement block can go without braces but the block must be properly indented on its own line and it must not be nested in other statement blocks that use braces. | ||
| 2. We use four spaces of indentation (no tabs). | ||
| 3. We use `_camelCase` for internal and private fields and use `readonly` where possible. Prefix instance fields with `_`, static fields with `s_` and thread static fields with `t_`. When used on static fields, `readonly` should come after `static` (i.e. `static readonly` not `readonly static`). |
There was a problem hiding this comment.
Personally, I don't really like _ prefix for instance fields - if the code is written in a way such prefix is needed to distinguish between fields and local parameters/variables, it should be rewritten to be clearer. But, I can live with that, so no change necessary.
There was a problem hiding this comment.
I agree with you. Internally we don't use the _ prefix for internal fields.
As I wasn't sure about others take on this I left it there. Removing it!
|
|
||
| See the license file at the root of project repositories for the specific license, such as with the following examples: | ||
|
|
||
| - [**nano Framework**](https://github.com/nano-framework/nf-interpreter/LICENSE.TXT) [(Apache 2)](https://opensource.org/licenses/Apache-2.0). |
There was a problem hiding this comment.
The link is broken, license is in LICENSE.md file (not .txt)
There was a problem hiding this comment.
Corrected. (great to have code reviews!!) ;)
| // Licensed to the nano Framework Contributors under one or more agreements. | ||
| // The .NET Foundation licenses this file to you under the Apache license. | ||
| // See the LICENSE file in the project root for more information. | ||
| ``` |
There was a problem hiding this comment.
I think that is license header required for/after joining the .NET Foundation. Until then, we should use something like
// Copyright (c) The nano Framework Interpreter project contributors
Optionally there could be year; and I am not sure about the leading 'The' (?)
There was a problem hiding this comment.
Remove the mention to the foundation. I replace it all over, but I missed this one...
As for the file header: I'm no expert on this but the majority of headers I've seen don't use the "copyright" wording there rather the "licensed to....". I have a feeling that this is there for a reason...
There was a problem hiding this comment.
Hm, IANAL too, but the vast majority of copyright notices I have seen are those 'copyright xxx' - except for the (relatively recent) projects under .NET Foundation, which are "Licensed to .NET Foundation...".
The proposed copyright header is based on information published in https://softwarefreedom.org/resources/2012/ManagingCopyrightInformation.html and github search for 'copyright ... project contributors'.
There was a problem hiding this comment.
As we are planning to apply to the foundation was saving time to use their header.
Anyways, just submitted those changes by copy/pasting the COPYRIGHT header as suggested in the link you've provided.
Please supply an appropriate text for the COPYRIGHT.md file.
I have no legal background that allows me to discuss this so I follow what seems reasonable and makes sense to me.
|
|
||
| [Clean-room](https://en.wikipedia.org/wiki/Clean_room_design) implementations of existing algorithms that are not permissively licensed will generally not be accepted. If you want to create or nominate such an implementation, please create an issue to discuss the idea. | ||
|
|
||
| <!--### Contributor License Agreement |
There was a problem hiding this comment.
IMHO CLA is rather important - there is https://github.com/clabot/clabot project that seems usable...
There was a problem hiding this comment.
Having contributors signing a CLA seems to be a good practice and becoming generalized.
I'm OK with adding that.
I'll uncomment this part and you'll add the clabot.
There was a problem hiding this comment.
I've pulled a CLA from http://www.harmonyagreements.org/index.html
